Context
A cached Docker build step is reusable only when its relevant inputs and prior steps still match. BuildKit is not remembering that a command looked familiar to a developer. It evaluates a build graph and cache records. A small source change can legitimately invalidate expensive dependency installation if that installation depends on a broad earlier copy.
You need the Dockerfile, build context, dependency lockfile, builder identity, and sanitized build log. Use an isolated development builder for experiments. The example build writes only a local test image and builder cache; it does not publish an image or change a running service.
1. Capture a reproducible baseline
docker buildx ls
docker buildx inspect
docker buildx build --progress=plain --load -t cache-review:local .
Run from the intended context directory. Compare the first uncached step in the log across builds. Check the selected builder and build arguments, since changing a builder or a relevant argument can explain a missed cache without any Dockerfile regression. Keep credential values out of diagnostic logs.
2. Narrow the dependency layer's inputs
Read the COPY and RUN sequence. A common repair is to copy package manifests and lockfiles, install dependencies, and only then copy frequently changing application source. The exact commands depend on the package manager and reproducibility requirements.
For an explicitly illustrative example, a Node-based build first copies package.json and package-lock.json and runs npm ci. It copies src afterward. A source-only change should leave the dependency-install step eligible for reuse, while a lockfile change should invalidate it. Add a .dockerignore that excludes unrelated output and local caches without excluding files the build genuinely needs.
3. Distinguish layer cache from cache mounts
A cache mount can preserve a package manager's download cache even when a RUN step must execute again. It is a performance aid, not a guaranteed input or an alternative to a lockfile.
# syntax=docker/dockerfile:1
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY src ./src
This fragment is illustrative and assumes the build user and package-manager cache location match those paths. Build output must remain correct if the cache mount is empty or has been garbage-collected. Also check your builder's documented export behavior: a local cache mount should not be assumed to travel with an external layer-cache export.
Classify the first avoidable miss
| Observation | Possible cause | Focused correction |
|---|---|---|
| Dependency step reruns after unrelated source edit | Broad early COPY | Separate stable dependency inputs |
| Every CI run starts cold | Ephemeral builder with no imported cache | Review supported external cache configuration |
| Cache mount seems empty on a new runner | Builder-local storage | Treat mount persistence separately |
| Build changes with unchanged lockfile | Unpinned or external inputs | Review dependency and toolchain reproducibility |
An external registry or CI cache needs explicit import/export configuration and a sensible scope. Avoid multiple jobs overwriting one cache location without a deliberate strategy. Do not place credentials in build arguments or copied files to make a cache-enabled build authenticate.
Verify behavior and maintain the build contract
Repeat an unchanged build, a source-only change, and a dependency-lockfile change. Confirm the expected cache reuse and invalidation in each case. Also run a clean build to verify the image does not depend on a warm package cache.
Document builder driver, context root, dependency inputs, cache backend, and cache ownership in the build SOP. Monitor build logs for changing first-miss locations and record timings as local observations if useful. Revisit cache boundaries when toolchains or dependency layout change, preserving correctness before optimizing repeated work.
Explore Clouvenix docker consulting for implementation and operational handover.