🚨 Ansible Error: 'Failed to update apt cache' — Cause, Fix, and Troubleshooting Guide

Overview

The apt module runs apt-get update when you set update_cache: true (or after adding a repo). If any configured repository cannot be reached or validated, the whole update fails and the task errors:

fatal: [web-01]: FAILED! => {"changed": false, "msg": "Failed to update apt cache: unknown reason"}

Or with detail:

fatal: [web-01]: FAILED! => {"msg": "Failed to update apt cache: W:GPG error: https://download.docker.com/linux/ubuntu jammy InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 7EA0A9C3F273FCD8"}

The cause is on the target host’s package configuration or network path.

Symptoms

• Any task with update_cache: true fails; package installs never run.
• Failure is per-host or per-repo — often a newly added third-party repo.
• Running apt-get update manually on the host reproduces the error.

ansible web-01 -i inventory.ini -b -m apt -a 'update_cache=true'

web-01 | FAILED! => {"msg": "Failed to update apt cache"}

Common Root Causes

1. Expired or missing GPG signing key

A repo’s key is not installed (or rotated), producing NO_PUBKEY / GPG error.

2. Unreachable mirror or DNS failure

The host cannot resolve or reach the mirror (offline network, wrong DNS, dead mirror).

3. Bad sources.list entry

A malformed or wrong-suite line (e.g. a repo that has no jammy release).

4. Proxy not configured

The host needs an HTTP proxy for outbound access and apt is not told about it.

How to diagnose

Run apt update on the host verbosely to see the real error:

ansible web-01 -i inventory.ini -b -m shell -a 'apt-get update 2>&1 | tail -n 20'

Check DNS/reachability to the mirror:

ansible web-01 -i inventory.ini -m shell -a 'getent hosts archive.ubuntu.com; curl -sSI http://archive.ubuntu.com/ubuntu/ | head -1'

Fixes

Install the repo’s signing key properly (keyring)

- name: Add Docker GPG key
  ansible.builtin.get_url:
    url: https://download.docker.com/linux/ubuntu/gpg
    dest: /etc/apt/keyrings/docker.asc
    mode: "0644"

- name: Add Docker repo
  ansible.builtin.apt_repository:
    repo: "deb [signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu {{ ansible_distribution_release }} stable"
    state: present
    update_cache: true

Make cache failures non-fatal when appropriate

- name: Update cache, tolerate transient mirror errors
  ansible.builtin.apt:
    update_cache: true
    cache_valid_time: 3600
  register: apt_update
  retries: 3
  delay: 10
  until: apt_update is succeeded

Configure a proxy for apt

- name: Configure apt proxy
  ansible.builtin.copy:
    dest: /etc/apt/apt.conf.d/95proxy
    content: 'Acquire::http::Proxy "http://proxy.internal:3128";'
    mode: "0644"

What to watch out for

• cache_valid_time avoids hammering mirrors and skips redundant updates within the window.
• Prefer signed-by= keyrings over the deprecated apt-key; that avoids the NO_PUBKEY class of failures.
• A single broken third-party repo fails the entire apt-get update — remove or fix the offending source, do not just retry.

Related

• Ansible Error: ‘No package matching found available’
• Ansible Error: ‘Could not get lock /var/lib/dpkg/lock’
• Ansible Error: ‘Failed to validate the SSL certificate’