CircleCI setup_remote_docker Version Errors - Fix the Daemon

A job using the remote Docker daemon fails - it pins an unsupported version, omits setup_remote_docker entirely, or assumes the remote daemon shares the job’s filesystem. The remote daemon is a separate environment with its own rules.

What this error means

The job errors on an unknown remote Docker version, cannot reach the daemon, or a volume mount / file copy into the build silently has no files - because the remote daemon does not see the job container’s filesystem.

Error: requested Docker version "20.10.unknown" is not supported.
# or
Cannot connect to the Docker daemon - did you add setup_remote_docker?
# or
docker run -v $PWD:/src ... : /src is empty (remote daemon, not local FS)

Common causes

Unsupported or retired version tag

The version under setup_remote_docker must be a currently-supported tag (or default). A retired or made-up version is rejected.

No setup_remote_docker before docker commands

On the docker executor there is no daemon until you add setup_remote_docker. Running docker build without it cannot connect.

Assuming the remote daemon shares the local filesystem

The remote daemon runs separately, so bind mounts (-v $PWD:/x) from the job container do not work. Files must be COPYed in the Dockerfile build context.

How to fix it

Add setup_remote_docker with a supported version

jobs:
  build-image:
    docker: [{ image: cimg/base:current }]
    steps:
      - checkout
      - setup_remote_docker:
          version: default     # or a currently-supported tag
      - run: docker build -t app .

Build context instead of bind-mounting

1. Use default for version unless you need a specific supported tag.
2. COPY files into the image via the Dockerfile rather than -v mounts.
3. For Docker-heavy jobs that need the local FS, use the machine executor instead.

How to prevent it

• Pin version: default (or a supported tag) for remote Docker.
• Always add setup_remote_docker before any docker command on the docker executor.
• Remember the remote daemon does not share the job filesystem - build via context.

Related guides