Troubleshooting Docker Layer Caching (DLC) Teardown Errors

Problem

Docker Layer Caching (DLC) speeds up builds by reusing Docker image layers. At the end of each DLC-enabled job, CircleCI runs a "DLC Teardown" step. When this step appears red in your build history, it means Docker images were pruned (removed) from the cache because they exceeded the 15 GiB storage limit.

Why this occurs: CircleCI automatically prunes images to keep DLC storage under 15 GiB. Pruned images cannot be reused in future builds, reducing DLC effectiveness.

Solutions

Solution 1: Identify Which Images Are Pruned

Add commands to list Docker images before and after your build:

steps:
  - run:
      name: List images before build
      command: docker image ls
  - checkout
  - setup_remote_docker:
      docker_layer_caching: true
  - run:
      name: Build image
      command: docker build -t my-image .
  - run:
      name: List images after build
      command: docker image ls

Compare the two lists in your build output to see which images were pruned during DLC Teardown.

Solution 2: Reduce Docker Image Size

Optimize your Dockerfile to keep images under 15 GiB:

• Use smaller base images (example: alpine instead of ubuntu)
• Combine RUN commands to reduce layers
• Remove unnecessary files and packages
• Use multi-stage builds

Example of combining commands:

RUN apt-get update && apt-get install -y \
    package1 \
    package2 \
    && rm -rf /var/lib/apt/lists/*

Solution 3: Remove Unused Images Before Teardown

Clean up unnecessary images during your build:

- run:
    name: Remove unused images
    command: docker image prune -f

Outcome

After implementing these solutions, check your next build. If the DLC Teardown step shows green, your images are within the 15 GiB limit and will be cached for future builds. If the step remains red, your images still exceed the limit and you should continue optimizing your Dockerfile.

Additional Notes

• The 15 GiB DLC storage limit applies across all projects in your organization
• The DLC Teardown step does not consume credits or cause build failures
• Cached layers expire after 3 days without use
• DLC is charged at 200 credits per job run

Additional Resources

• Docker Layer Caching Overview - Understanding how DLC works
• Docker Best Practices - Optimizing Dockerfiles and reducing image size
• How to Debug Docker Layer Cache Misses - Troubleshooting DLC cache issues
• Docker Layer Caching FAQ - Common questions about DLC