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:

- setup_remote_docker:
    docker_layer_caching: true

Machine executor:

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:

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: true
• Dockerfile 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