Cannot connect to the Docker daemon

WHAT IT MEANS

What this error means

Container builds require Docker even for transient validation steps. The message tells you which layer is missing:

• docker: not found / is not recognized — the Docker CLI is not installed on the machine or runner at all.
• Cannot connect to the Docker daemon / docker.sock: No such file or directory — the CLI exists but the daemon is not running, or the current user cannot reach the socket.
• Error response from daemon — the daemon is up but rejected the operation (disk full, image platform mismatch, network restriction).

Common environments where this bites: macOS/Windows machines where Docker Desktop is installed but not started; Linux users not in the docker group; CI containers running inside Docker without the socket mounted; minimal self-hosted runners; and GitHub-hosted macos-* runners, which do not ship a working Docker daemon.

FIX

How to fix it

1. Confirm the state on the failing machine:

   docker version

   If the client prints but the server section errors, it is a daemon or socket problem, not an installation problem.
2. Local machine: start Docker Desktop (macOS/Windows) or the service (Linux: sudo systemctl start docker). On Linux, add yourself to the docker group and re-login if plain docker ps is denied.
3. Self-hosted runner: check that the Docker service is enabled and the runner user can access /var/run/docker.sock. If the runner itself is a container, mount the socket or run a docker-in-docker sidecar deliberately.
4. GitHub-hosted runners: ubuntu-* runners have Docker ready; macos-* runners do not. Move container builds to an Ubuntu job.
5. Or remove the Docker requirement. If the function is ZIP-packaged and has no native dependencies, build without the container:

   sam build            # instead of: sam build --use-container

   Keep --use-container when you need native wheels compiled for the Lambda runtime — in that case Docker is genuinely required.

AUTOMATE THE TRIAGE

Diagnose this automatically

SAM Doctor recognizes the full family of Docker-unavailable messages (high confidence) and separates them from ECR authentication and image permission failures that also mention Docker. Runs locally; no AWS access, no log upload.

python -m pip install sam-doctor
sam-doctor diagnose deployment.log --format markdown

RELATED

Related errors

• no basic auth credentials — Docker works, but the push to ECR is unauthenticated.
• Esbuild Failed: Cannot find esbuild — the Node.js build-time neighbor of this failure.
• InsufficientCapabilitiesException — the next stop once the build finally succeeds.