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 dockerIf 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:5000Finally, 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 proxyTechnical 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
| Cause | Description |
|---|---|
| Daemon Inactive | The local Docker engine is not running, preventing any CLI commands from executing. |
| Port Mismatch | The registry is listening on a different port than the one specified in the login command. |
| Firewall/WAF | A local or network firewall is blocking outbound traffic on port 443 or 5000. |
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-stdinAnother 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 loginIf 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.