Trace a Docker client-to-daemon connection failure

Investigate a failed Docker connection in three layers: the client's selected endpoint, access to that transport, and the daemon behind it. This keeps a stale context, a denied socket, and a daemon crash from being treated as the same problem.

1. Resolve the client's destination

docker context show
docker context ls
printf 'DOCKER_HOST=%s\nDOCKER_CONTEXT=%s\n' "${DOCKER_HOST-}" "${DOCKER_CONTEXT-}"

Inspect the relevant context with docker context inspect CONTEXT_NAME. Command-line flags and environment overrides can change the selected endpoint. A nonempty DOCKER_HOST may name a local socket; it does not necessarily mean the daemon is remote.

Tools such as a local Kubernetes environment can intentionally change Docker-related variables. Restore the intended configuration once identified. Do not blindly choose the default context: Desktop or rootless setups may correctly use a different one.

2. Check the actual transport

For a conventional native Linux socket:

ls -l /var/run/docker.sock
id

Use the path selected in the previous step, which may differ from this example. A missing file can mean a stopped daemon, a different socket location, or a missing integration. Permission denied calls for checking ownership, numeric groups, ACLs, and security policy. A socket file can also exist without a responsive daemon.

For SSH or TLS, inspect host reachability and authentication rather than applying Unix socket group instructions. Avoid printing private keys or tokens while collecting diagnostics.

3. Inspect the matching service

For a system-managed Linux Engine:

sudo systemctl status docker
sudo journalctl -u docker -n 100 --no-pager
sudo systemctl cat docker

For a rootless user service, use the corresponding systemctl --user and user journal. Compare daemon flags with its configuration file: duplicate settings supplied through both can prevent startup. A valid JSON file is not necessarily valid daemon configuration.

A crash loop is a symptom, not proof that reinstalling is required. Preserve the diagnostic evidence and storage before considering disruptive recovery.

Desktop and WSL

Confirm Desktop's engine state and selected context, then use its diagnostics. In WSL, check distribution integration and whether a separate Linux Engine was also installed. Restarting the intended engine may be a recovery step; a factory reset can remove data and should not be treated as equivalent to a restart.

FAQ

Why does sudo work?

It may gain socket access, but it may also select another context or configuration. Compare destinations first. If only credentials differ on the same rootful socket, review group access for the actual user or service account.

Why is systemctl active but the client still fails?

Check the endpoint, access controls, API responsiveness, and startup completion. “Active” alone does not identify which one failed.

Should I reinstall?

Only after evidence points to installation damage and you have planned data preservation. Reinstallation does not repair a wrong context, stale credentials, or a full filesystem by itself.

See daemon troubleshooting and Docker contexts.