Introduction
When Docker Layer Caching (DLC) doesn't reuse cached layers, builds run slower. This guide helps you identify why cache misses happen in CircleCI Cloud builds.
Note: This guide applies only to CircleCI Cloud, not CircleCI Server.
Prerequisites
CircleCI Cloud project with DLC enabled
Two builds to compare (one with cache hit, one with cache miss)
Access to build logs
Instructions
Step 1: Verify DLC Is Enabled
Check that your configuration has docker_layer_caching: true:
Remote Docker:
yaml
- setup_remote_docker:
docker_layer_caching: trueMachine executor:
yaml
machine: docker_layer_caching: true
Look for "Restoring DLC" in the Spin up environment step. If missing, DLC is not enabled.
Step 2: Check for Dockerfile Changes
Any change to a Dockerfile invalidates the cache from that point forward. Compare your Dockerfiles and check:
Modified RUN, ADD, or COPY commands
Changed instruction order
Updated base images
Step 3: Check for Image Pruning
Add these commands to see if images exceeded the 15 GiB limit:
yaml
steps: - run: docker image ls - checkout - run: docker build -t test . - run: docker image ls
Compare the lists. Check DLC Teardown output for pruned images.
Step 4: Check Cache Expiration
If more than three days pass between builds, the cache expires.
Outcome
You should now know why the cache miss occurred:
DLC not enabled: Add
docker_layer_caching: trueDockerfile changed: Expected behavior; future builds will cache new layers
Images pruned: Reduce image size under 15 GiB
Cache expired: Run builds more frequently
Additional Notes
DLC Teardown does not consume credits
Cache uploads are asynchronous; jobs in the same workflow may not share cache.
Cached layers expire after 3 days
Additional Resources
Docker Layer Caching Overview - How DLC works
Docker Best Practices - Optimizing Dockerfiles
Docker Layer Caching FAQ - Common questions
Troubleshooting DLC Teardown Errors - Resolving errors