Q: Your container image build is failing on `apt-get update`. What's likely wrong?
A build failing on apt-get update is usually a network or repository problem, not an apt bug: DNS or proxy settings inside the build, an end-of-life release whose repos moved, an expired or missing GPG key, or a clock mismatch.
Want to master this scenario in a live sandbox? KodeKloud's Docker Certified Associate (DCA) Hands-On Lab Course covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: A <strong>build failing on apt-get update</strong> is usually a network or repository problem, not an apt bug: DNS or proxy settings inside the build, an end-of-life release whose repos moved, an expired or missing GPG key, or a clock mismatch. Interviewers ask it to see whether you troubleshoot in order, using the exact error text rather than guessing. The runbook is to reproduce outside the build, read the specific error, isolate network from repository issues, fix the root cause and then harden the Dockerfile so it stays reliable.
Symptom to cause map
Start from the message, because each one points at a different layer.
- Temporary failure resolving 'deb.debian.org': DNS. The build container cannot resolve names, often due to a corporate resolver or a broken
/etc/docker/daemon.jsonDNS setting. - Could not connect / connection timed out: proxy, firewall, or an IPv6 route that does not work.
- 404 Not Found or 'does not have a Release file': the distribution is end of life and its repos moved. For example EOL Debian releases go to
archive.debian.organd EOL non-LTS Ubuntu releases toold-releases.ubuntu.com. - NO_PUBKEY, invalid signatures, 'Release file is not valid yet': missing or expired key, or clock skew, often on a Docker Desktop VM after sleep.
- Hash Sum mismatch: a caching proxy or mirror in the middle serving partial content.
Hands-on: reproduce a build failing on apt-get update
Remove Docker build noise and test the failing step in isolation. Change one variable at a time so the result is attributable.
docker build --progress=plain --no-cache -t test .
docker run --rm -it debian:bookworm bash -c 'apt-get update'
docker run --rm busybox nslookup deb.debian.org
docker run --rm curlimages/curl -sSI https://deb.debian.org
# Is it Docker's bridge network?
docker build --network host -t test .
- Full output: rerun with
docker build --progress=plain --no-cache .to see every line and bypass a cached bad layer. - Same base, interactively: run the base image and execute the command by hand.
- Test DNS and connectivity: check resolution and an HTTPS fetch from a throwaway container.
- Try the host network:
docker build --network host .tells you whether Docker's bridge networking is the culprit. - Architecture mismatch: on ARM builders or emulated builds some third-party repositories do not publish the architecture you need, and
apt-get updatewarns or fails for that source only. Checkdpkg --print-architecture.
Fix the root cause
Apply the fix that matches the diagnosis.
# Stopgap for an EOL Debian release (prefer upgrading the base image)
RUN sed -i 's|deb.debian.org|archive.debian.org|g' /etc/apt/sources.list
# Proxy at build time
# docker build --build-arg HTTPS_PROXY=http://proxy.example.com:3128 .
- DNS: set resolvers in
/etc/docker/daemon.json(for example{"dns": ["10.0.0.2", "8.8.8.8"]}using your resolver), then restart the daemon. - Proxy: pass
--build-arg HTTP_PROXY=... --build-arg HTTPS_PROXY=.... These are predefined build args and do not need anARGline. Add your corporate CA withca-certificatesif TLS is intercepted. - EOL release: the real fix is a supported base image tag. As a stopgap point sources at the archive host.
- Clock or keys: restart Docker Desktop to resync the VM clock. For third-party repos, install the signing key into
/etc/apt/keyringswithsigned-by=instead of the deprecatedapt-key. - IPv6 problems: if the build host has a broken IPv6 route, apt may hang trying AAAA addresses first. Forcing IPv4 with
-o Acquire::ForceIPv4=trueconfirms it as the cause.
Harden the Dockerfile pattern
Many intermittent failures come from how the step is written. Treat the Dockerfile as code that runs on many networks, not only yours.
RUN apt-get update -o Acquire::Retries=3 \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
ca-certificates curl \
&& rm -rf /var/lib/apt/lists/*
- Combine in one layer:
apt-get update && apt-get installin oneRUN. A separate cachedupdatelayer goes stale and later installs hit 404 on outdated package indexes. - Non-interactive: set
DEBIAN_FRONTEND=noninteractivefor the step only and use-y. - Retries:
-o Acquire::Retries=3smooths over transient mirror hiccups. - Clean up: remove
/var/lib/apt/lists/*in the same layer to keep the image small. - Ownership of the fix: network and proxy issues belong to platform or network teams, so bring them the exact failing hostname and command output rather than a vague report that the build is broken.
Verification and prevention
Confirm the fix and keep it from recurring.
- Verify: a clean
docker build --no-cachepasses, and CI passes on a fresh runner, not only on your cached laptop. - Mirror dependencies: use an internal package mirror or pull-through registry so builds do not depend on public mirrors.
- Track base image EOL: schedule base image upgrades and scan for unsupported distributions.
- Pin and rebuild regularly: pin base images by digest and rebuild weekly so repo drift shows up early.
- BuildKit secrets: if a private repository needs credentials, pass them with a BuildKit secret mount, never as a build argument that gets stored in image history.
- I reproduce the failure with <code>--progress=plain --no-cache</code> and by running <code>apt-get update</code> by hand in the base image.
- I classify by message: DNS or proxy, EOL repositories, GPG or clock, or a bad mirror, and test DNS and HTTPS from a throwaway container.
- I fix the cause, keep update and install in a single layer with retries, and use a supported, pinned base image with an internal mirror.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Putting apt-get update in its own RUN layer The layer is cached, so a later install can use a stale index and fail with 404 errors.
- Staying on an EOL base image and patching sources forever Repos move and eventually stop updating, so security fixes are gone. Upgrade the base image.
- Using apt-key add or disabling signature checks apt-key is deprecated and bypassing signatures removes supply-chain protection. Use signed-by keyrings.
- Debugging only with cached builds A cached layer hides the failure on your machine while a clean CI runner breaks. Use --no-cache when diagnosing.