docker connection_error ai_generated true

error during connect: in the default daemon configuration on Windows, the docker client must be run with elevated privileges

ID: docker/wsl2-docker-connect-failed

Also available as: JSON · Markdown
88%Fix Rate
85%Confidence
110Evidence
2021-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
27 active — — —

Root Cause

Docker client in WSL2 cannot connect to the Docker daemon. Usually caused by Docker Desktop WSL2 integration not enabled, Docker Desktop not running, or DOCKER_HOST pointing to the wrong socket.

generic

Workarounds

  1. 92% success Enable WSL2 integration in Docker Desktop settings 
    Docker Desktop > Settings > Resources > WSL Integration > Enable integration with your WSL distro. Then restart Docker Desktop and run 'wsl --shutdown' followed by reopening your WSL terminal.

    Sources: https://docs.docker.com/desktop/wsl/

  2. 90% success Ensure Docker Desktop is running before using docker CLI in WSL2 
    Start Docker Desktop from the Windows Start menu. Wait for the whale icon in the system tray to stabilize. Then retry docker commands in WSL2.

    Sources: https://docs.docker.com/desktop/

  3. 80% success Unset DOCKER_HOST if it points to the wrong socket 
    echo $DOCKER_HOST
# If set, unset it:
unset DOCKER_HOST
# The default socket /var/run/docker.sock should be used via WSL2 integration

Dead Ends

Common approaches that don't work:

  1. Installing Docker Engine natively inside WSL2 alongside Docker Desktop 75% fail

    Running two Docker daemons (Docker Desktop + native) causes socket conflicts and confusing behavior. Images/containers are split between the two daemons.

  2. Running dockerd manually with sudo inside WSL2 70% fail

    If Docker Desktop is managing the daemon, running a second dockerd creates conflicts. If Docker Desktop is not installed, systemd may not be available in older WSL2 distros.

Error Chain

Frequently confused with: