A CircleCI job that uses the docker executor runs docker build and fails because no Docker daemon is reachable. Why does that happen, and what are your two options?

## Executors are chosen, not inferred A CircleCI job names its execution environment explicitly. There are four families: `docker` (your steps run inside a container image you specify), `machine` (a full Linux VM), `macos` (a macOS VM, selected by Xcode version), and Windows, which is provided through an orb-supplied executor rather than as a bare key. This is the design contrast the leaf exists for: instead of picking a runner label and inheriting whatever that pool happens to provide, you state the environment in the job definition. That explicitness is exactly why the failure in the question surprises people. The `docker` executor is the default choice because it starts fastest, but a container is not a machine, and the platform does not quietly hand you a daemon. ## Why the docker executor has no daemon Under the `docker` executor your steps execute inside a container scheduled on shared infrastructure. Exposing the host's Docker socket into that container would hand every build effective control of the host and of its neighbours — that is a privilege boundary, not an oversight. So `docker build`, `docker run`, `docker compose` and anything else that needs to talk to a daemon fail with a connection error. ## Option one: `setup_remote_docker` Adding the `setup_remote_docker` step provisions a **separate, isolated Docker environment** for the job and configures the job's Docker CLI to talk to it. The job keeps the fast-starting container, and image builds work. ```yaml version: 2.1 jobs: build-image: docker: - image: cimg/base:current steps: - checkout - setup_remote_docker - run: docker build -t myapp:$CIRCLE_SHA1 . ``` The constraint to remember — and the one interviewers probe — is that **the remote environment does not share a filesystem with your job's container**. The build context is sent over, so `docker build .` works, but bind-mounting a path from your working directory into a container you start (`docker run -v $(pwd):/src ...`) does not behave as it would locally, because the remote daemon cannot see that path. The workaround is to copy files into the container explicitly with `docker cp`, or to bake what you need into the image. Ports published by containers started remotely are likewise not reachable at `localhost` from the job. On CircleCI's paid plans, `setup_remote_docker` also accepts `docker_layer_caching: true`, which preserves layers between runs so unchanged Dockerfile stages are not rebuilt. ## Option two: the machine executor Declaring `machine:` with a CircleCI-provided image gives the job a dedicated VM: ```yaml jobs: build-image: machine: image: ubuntu-2204:current steps: - checkout - run: docker build -t myapp:$CIRCLE_SHA1 . ``` Here the daemon is local, so volumes, published ports and multi-container setups behave the way they do on a laptop — which matters for integration tests that start dependencies with `docker compose` and mount fixtures into them. The price is start-up time: a VM boots more slowly than a container, and the resource classes cost more. There is no daemon-reachability puzzle to explain to teammates, though, which has its own value. ## Choosing between them - Building and pushing an image with no volume mounting: `docker` executor plus `setup_remote_docker`. Fastest, and the common case. - Integration tests that mount host paths, publish ports, or run `docker compose` with local networking: `machine`. Fighting the remote environment here costs more than the slower boot. - Anything needing kernel-level access, privileged containers, or nested virtualization: `machine`. - Building and testing an application without touching Docker at all: `docker` executor with a language image, no remote Docker. ## The related trap The image listed under a `docker:` executor is the environment your **steps run in**, not the image you are building. A candidate who tries to fix the daemon error by changing that image to something Docker-flavoured has misread the failure: the missing thing is a daemon to connect to, not a client binary. Say that explicitly and the diagnosis reads as lived experience rather than recall.