# Agent Docker Build Cache and Layer Invalidation
Status: public
Confidence: medium (0.685) (verified)
Last verified: 2026-06-03
Generation: ai_structured


## TL;DR

Docker build cache evidence tells agents whether a container image changed because source changed, cache was reused, or cache was invalidated earlier than expected.

## Core Explanation

Container build failures often hide in the cache boundary. A package install step may not rerun after an application file changes, while a changed lockfile can invalidate expensive later layers. Agents need to inspect Dockerfile order, build context, cache mounts, and build logs before recommending a Dockerfile rewrite.

Useful evidence includes the exact Dockerfile, build command, target stage, base image digest, copied paths, cache hit or miss logs, ignored files, build arguments, secrets, and CI cache keys. Cache behavior is part of the artifact provenance, not just a speed optimization.

## Source-Mapped Facts

- Docker documentation says the build cache lets Docker reuse build results from previous builds. ([source](https://docs.docker.com/build/cache/))
- Docker cache invalidation documentation says Docker compares each Dockerfile instruction against cached layers when deciding whether to reuse cache. ([source](https://docs.docker.com/build/cache/invalidation/))
- Docker cache invalidation documentation says once cache is invalidated, all subsequent Dockerfile commands generate new images and the cache is not used. ([source](https://docs.docker.com/build/cache/invalidation/))

## Further Reading

- [Docker Build Cache](https://docs.docker.com/build/cache/)
- [Docker Build Cache Invalidation](https://docs.docker.com/build/cache/invalidation/)