Fix Docker Login Connection Refused [Solved]

Immediate Fix

The “Connection Refused” error during a Docker login usually means the Docker daemon is unreachable or the registry endpoint is blocked. The first step is to ensure your Docker service is actually running.

# Check Docker status
sudo systemctl status docker

# Start Docker if it is stopped
sudo systemctl start docker

If the daemon is running, verify that you are hitting the correct registry URL. If you are using a private registry, ensure you include the port number (default is 5000).

# Example for a private registry
docker login my-registry.example.com:5000

Finally, check your system’s proxy settings. If you are behind a corporate firewall, Docker may be trying to route through a proxy that doesn’t allow traffic to the registry.

# View current proxy environment variables
env | grep -i proxy

Technical Explanation

A “Connection Refused” (ECONNREFUSED) message indicates that the client attempted to establish a TCP connection with the host, but the host actively rejected it. In the context of Docker, this happens at the transport layer.

This failure typically occurs for three reasons: the service isn’t listening on the target port, a firewall is dropping the packets, or the Docker socket permissions are misconfigured. When you run docker login, the CLI sends an HTTPS request to the registry’s /v2/ endpoint. If the registry container is down or the network path is severed, the handshake fails immediately.

Common Root Causes

Alternative Methods

If the standard login still fails, try bypassing the local credential helper. Sometimes the issue lies with the docker-credential-desktop or gnome-keyring failing to initialize, causing a timeout that looks like a connection refusal.

# Try logging in by passing credentials via STDIN
echo "PASSWORD" | docker login -u "USERNAME" --password-stdin

Another method is to inspect and reset your ~/.docker/config.json file. Corrupted authentication objects in this file can lead to unexpected connection errors during the challenge-response phase of the login.

# Backup and remove existing config
mv ~/.docker/config.json ~/.docker/config.json.bak
# Attempt login again
docker login

If you are using Docker Desktop on Windows or Mac, ensure that the “Expose daemon on tcp://localhost:2375 without TLS” setting is toggled correctly if your scripts rely on direct TCP connections rather than the default Unix socket.