Error communicating with Docker daemon when restoring Docker Layer Cache with multi-arch builds

This can happen before build steps run — with an Infrastructure Failure badge and an error like:

error communicating with docker daemon: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

This often appears intermittently (re-running the job may succeed) and is commonly tied to multi-architecture image builds that register QEMU/binfmt handlers on the Remote Docker host.

The failure is usually caused by a corrupted DLC snapshot, not by your Dockerfile or application code.

Overview

When a job installs QEMU/binfmt support for multi-arch builds (for example with tonistiigi/binfmt or multiarch/qemu-user-static) and has DLC enabled, those handlers can leave dangling filesystem references on the Remote Docker host.

At the end of the job, if binfmt handlers are still registered, the DLC snapshot can become corrupt. The next job that restores the cache may then fail when the Docker daemon cannot start.

Purging DLC alone is not enough. Any later job that installs binfmt without cleaning up can re-corrupt the cache when it saves.

Affected Projects

Your project may be affected if all of the following are true:

docker_layer_caching: true on setup_remote_docker or the machine executor
Multi-arch builds using docker buildx with --platform linux/amd64,linux/arm64 (or similar)
A QEMU/binfmt setup step such as:
- docker run --privileged --rm tonistiigi/binfmt --install all
- docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
- an equivalent command from a custom orb or mirror

The same Docker daemon error can also appear from other DLC corruption causes (for example after a Docker engine version change). The cleanup steps below are specifically required for multi-arch builds that register binfmt with DLC enabled. In other cases simply purging your project's DLC or pinning your Docker version may resolve the issue.

Solution

Complete all three steps below. Skipping any one of them can leave the cache corrupt or allow it to become corrupt again.

1. Add a binfmt cleanup step (required)

Add this as the last step in any job that installs QEMU/binfmt and uses DLC. The use of when: always is important so cleanup runs even if an earlier step fails — otherwise a failed build can still save a corrupt cache.

Recommended (if you use tonistiigi/binfmt):

- run:
    name: Clean up multi-architecture build artifacts
    when: always
    command: docker run --privileged --rm tonistiigi/binfmt --uninstall qemu-*

If you mirror or pin the binfmt image (recommended), the above step may need to be tweaked to reflect the specific image you are using.

Alternative (manual binfmt_misc cleanup):

- run:
    name: Clean up multi-architecture build artifacts
    when: always
    command: |
      docker run --rm --privileged busybox sh -c '
        for f in /proc/sys/fs/binfmt_misc/qemu-*; do
          echo -1 > "$f" 2>/dev/null
        done
      '

Prefer the tonistiigi/binfmt --uninstall form when possible. If the install step lives in a private orb or shared job template, add the cleanup there so every consumer inherits the fix.

2. Purge the project’s DLC cache

Clear the existing corrupt snapshot after the cleanup step is in place:

Web app: Project Settings → Docker Layer Caching → Delete Cache Contents
CLI: circleci project dlc purge <vcs-type> <org> <project>

See Purge DLC for more details.

3. Roll out cleanup on every active branch

DLC is project-scoped. Any branch that runs multi-arch setup without the cleanup step can write a corrupt cache that affects later jobs on other branches.

Merge or cherry-pick the cleanup to all active feature branches, not only main. Once this has been rolled out purge DLC once more.

Recommended hardening

Pin your binfmt image

Avoid :latest on QEMU setup images so silent image updates do not change behaviour unexpectedly:

docker run --privileged --rm tonistiigi/binfmt:qemu-v7.0.0 --install all

Match the tag to whatever your build already uses. The important part is pinning a specific version, and using that same image for --uninstall.

Use a named Buildx builder with DLC

When using buildx, unnamed builders get random names and their volumes may not be preserved correctly across runs. See Buildx builder instances:

- run:
    name: Create Buildx builder
    command: |
      docker buildx create --name my-dlc-builder --use
      docker buildx inspect --bootstrap

Temporary mitigation

If you need builds to stabilise immediately while you roll out the cleanup set docker_layer_caching: false on the affected Remote Docker / machine jobs until the uninstall step is live on all active branches and DLC has been purged.

Example job configuration with cleanup step

version: 2.1

jobs:
  multi-arch-build:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: true
      - run:
          name: Register QEMU binfmt
          command: docker run --privileged --rm tonistiigi/binfmt:qemu-v7.0.0 --install all
      - run:
          name: Create Buildx builder
          command: |
            docker buildx create --name my-dlc-builder --use
            docker buildx inspect --bootstrap
      - run:
          name: Multi-arch build
          command: |
            docker buildx build --platform linux/amd64,linux/arm64 -t my-image:test .
      - run:
          name: Clean up multi-architecture build artifacts
          when: always
          command: docker run --privileged --rm tonistiigi/binfmt:qemu-v7.0.0 --uninstall qemu-*

Outcome

After the cleanup step is live on every branch that writes DLC, and the project cache has been purged:

New jobs should no longer fail at spin-up with the Docker daemon connection error caused by this corruption
Subsequent multi-arch jobs can keep DLC enabled without re-corrupting the snapshot
Re-runs should stop oscillating between success and Infrastructure Failure for this cause

If failures continue after steps 1–3, confirm no other branch or orb job still installs binfmt without cleanup. If the failures persist after this please contact support with a recent failing job URL.