Docker Layer Caching cache invalidation fails when non-context files change in CircleCI 2.1

Docker Layer Caching in CircleCI 2.1

Docker Layer Caching (DLC) was introduced in CircleCI 2.1 to store Docker image layers between jobs, reducing build times. It is enabled via the docker_layer_caching: true flag and only works with the Docker executor on plans that support caching.

Cache Key Behavior

The DLC cache key is derived from the Dockerfile and the build context. However, changes to files outside the Docker build context—such as a README or script not copied into the image—do not trigger cache invalidation. This can result in stale layers being reused even when the final image should differ.

Unresolved Behavior

When a non-context file changes, CircleCI may still serve a cached layer, leading to inconsistent build outputs. The documentation does not clarify whether this is intentional or a limitation, nor does it provide a mechanism to force invalidation based on arbitrary file changes.

Questions

• Is the absence of cache invalidation for non-context file changes an intentional design decision or an undocumented limitation?
• Can users configure CircleCI to invalidate DLC caches based on files outside the Docker build context?
• Has this behavior been addressed in any recent CircleCI version or roadmap?