Introduction

On macOS, this error usually means the Docker CLI cannot reach the engine backend that Docker Desktop or another local runtime manages. The fix is rarely "restart the daemon blindly"; you need to check whether Docker Desktop is running, whether the CLI is pointing at the right context or socket, and whether an old DOCKER_HOST setting is forcing the client to a dead endpoint.

What Is Actually Running on macOS

Unlike a typical native Linux setup, Docker on macOS does not run the container engine directly in the host kernel. The CLI usually talks to a local backend managed by Docker Desktop or an alternative runtime such as Colima or OrbStack.

That means there are three things to verify:

• the desktop or runtime service is started
• the Docker CLI context points to the correct backend
• the environment is not overriding the connection settings

If any one of those is wrong, docker ps and similar commands fail even though Docker is installed.

First Diagnostic Commands

Start with:

docker version
docker context ls
docker info

These commands tell you:

• whether the client itself is installed
• which Docker context is active
• whether the engine is reachable

If the client section prints but the server section fails, the CLI is installed but the engine connection is broken.

Make Sure Docker Desktop Is Running

If you use Docker Desktop, open it and wait until it finishes initialization. Then retry:

docker ps

Many "couldn't connect" errors are simply caused by Docker Desktop not being fully started yet. On macOS, launching the app matters because the CLI alone does not start the engine backend for you in every case.

Check the Active Docker Context

An incorrect context is a common cause, especially if you previously used remote Docker hosts, Colima, or other runtimes.

List contexts:

docker context ls

Switch to the default local context:

docker context use default

If Docker Desktop created its own context, switch to that one instead. The point is to use the context that corresponds to the engine you actually started.

Remove a Bad DOCKER_HOST

Old shell profiles often export DOCKER_HOST, forcing the client to use a socket or TCP address that no longer exists.

Check:

echo $DOCKER_HOST

If it prints a value you are not intentionally using, unset it:

unset DOCKER_HOST

Then retry docker version. If this solves the issue, remove the old export from your shell startup file such as .zshrc or .bash_profile.

Alternative Runtimes Need Their Own Startup

If you are not using Docker Desktop, the fix may be specific to the runtime. For example, a CLI configured for Colima will fail until Colima is actually started.

Typical workflow:

colima start
docker context ls
docker ps

The key point is that the Docker CLI is only a client. It still needs a real backend somewhere.

Socket and Permission Clues

You can also inspect the active socket:

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

On macOS, the exact socket path depends on the runtime. If the active context expects a socket that is missing, the failure is not about permissions yet; it is about a backend that never started or a client aimed at the wrong place.

Resetting the Environment

If the context and environment look correct but the engine still will not answer, restart the runtime cleanly. For Docker Desktop that often means quitting the app and relaunching it. If the problem persists, resetting Docker Desktop's internal state may help, but do that only after confirming the simpler connection causes first.

The right order is:

1. confirm runtime is running
2. confirm context
3. confirm DOCKER_HOST
4. restart runtime
5. reset or reinstall only if the connection is still broken

Common Pitfalls

• Treating the error as a Linux-style daemon issue and forgetting that macOS usually relies on Docker Desktop or another managed backend.
• Leaving an old DOCKER_HOST export in the shell environment, which points the client at a dead socket or TCP endpoint.
• Switching between Docker Desktop and alternative runtimes without checking the active Docker context.
• Running the Docker CLI immediately after opening Docker Desktop and assuming the backend is ready before initialization finishes.
• Jumping to reinstall Docker before checking docker context ls and the environment variables that actually control the connection.

Summary

• On macOS, this error usually means the Docker CLI cannot reach the local backend, not that the client binary is missing.
• First verify the runtime is running, then inspect the active Docker context.
• Remove stale DOCKER_HOST overrides if present.
• If you use an alternative runtime such as Colima, make sure that runtime is started and selected.
• Diagnose the connection path before reinstalling anything; most failures are context or backend startup problems.