🚨 Docker Error Guide: 'Error while fetching server API version' — Daemon Not Reachable

Overview

Compose (especially the Python-based v1) cannot reach the Docker daemon and aborts before doing anything:

Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

Compose’s very first action is to open the Docker API socket and negotiate an API version. The FileNotFoundError(2, ...) is the operating system saying the socket file at /var/run/docker.sock does not exist — which happens when the daemon is not running, the socket lives somewhere else, or DOCKER_HOST points at a target that is not there. It is a connectivity error, not a Compose file error.

Symptoms

• Every docker-compose / docker compose command fails instantly with the same “fetching server API version” message.
• docker ps also fails with Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
• The error mentions FileNotFoundError(2, 'No such file or directory') (no socket) or ConnectionRefusedError (socket exists, daemon down).
• On a laptop, Docker Desktop is installed but not started.
• Inside CI or a container, DOCKER_HOST is set to a socket or TCP endpoint that is not actually available.

Common Root Causes

• The Docker daemon is not running. No dockerd, so no socket to connect to.
• Docker Desktop is stopped (macOS/Windows/WSL), so the socket the CLI expects is absent.
• DOCKER_HOST points at the wrong place — a stale tcp:// or unix:// path that does not exist.
• Missing permission on the socket produces a related connection failure for non-root users not in the docker group.
• Rootless Docker socket path. Rootless mode uses $XDG_RUNTIME_DIR/docker.sock, not /var/run/docker.sock, so the default lookup fails.
• Docker-in-Docker misconfiguration in CI, where the docker service/sidecar has not started or is reachable at a different host.

Diagnostic Workflow

Confirm whether the daemon is up. On a systemd host:

systemctl status docker
sudo systemctl start docker

Check whether the socket file actually exists and who owns it:

ls -l /var/run/docker.sock

If the socket is missing, the daemon is not running (or is rootless elsewhere). If it exists but you get permission errors, check your group membership:

groups

Look for an overriding DOCKER_HOST that redirects the client away from the local socket:

echo "$DOCKER_HOST"
docker context ls

Once the daemon is reachable, prove connectivity before retrying Compose:

docker ps
docker compose version
docker compose up -d

Example Root Cause Analysis

A developer set DOCKER_HOST=unix:///var/run/docker.sock in their shell profile months earlier to work around an unrelated issue, then forgot about it. Later they switched to rootless Docker, whose socket lives at $XDG_RUNTIME_DIR/docker.sock (e.g. /run/user/1000/docker.sock), and the correct docker context was configured to use it.

Because the hardcoded DOCKER_HOST environment variable overrides the active context, every command tried to open /var/run/docker.sock — which does not exist under rootless mode. Compose failed with Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory')), and ls -l /var/run/docker.sock confirmed the file was absent.

The fix was to unset the stale variable (unset DOCKER_HOST and remove it from the profile) so the client fell back to the correct rootless context. docker context ls then showed the rootless endpoint active, docker ps connected, and Compose worked. The lesson: an explicit DOCKER_HOST silently wins over docker context, so a leftover value can point the client at a socket that no longer exists.

Prevention Best Practices

• Ensure the daemon starts on boot: sudo systemctl enable --now docker on servers, and let Docker Desktop launch at login on workstations.
• Prefer docker context over hardcoding DOCKER_HOST. Contexts are switchable and avoid stale overrides; unset lingering DOCKER_HOST values.
• Add users to the docker group (or use rootless mode) so socket permissions do not cause connection failures.
• In CI, wait for the daemon. Poll docker ps (or the Docker-in-Docker socket) until it responds before running Compose.
• Document the socket path per mode — rootful uses /var/run/docker.sock, rootless uses $XDG_RUNTIME_DIR/docker.sock. See the Docker stack guides.

Quick Command Reference

# Is the daemon running?
systemctl status docker
sudo systemctl start docker

# Does the socket exist, and who owns it?
ls -l /var/run/docker.sock

# Is a stale DOCKER_HOST redirecting the client?
echo "$DOCKER_HOST"
docker context ls

# Prove connectivity, then run Compose
docker ps && docker compose up -d

Conclusion

Error while fetching server API version: ('Connection aborted.', FileNotFoundError...) means Compose could not open the Docker API socket — almost always because the daemon is stopped or the client is pointed at a socket path that does not exist. Confirm systemctl status docker, check ls -l /var/run/docker.sock, and clear any stale DOCKER_HOST. Once docker ps connects, Compose will too.