What causes "proxyconnect tcp: dial tcp: connection refused (proxy)"?

Proxy server configured in Docker but not actually running Proxy settings left over from previous network configuration Corporate proxy requires authentication credentials not provided

How to fix proxyconnect tcp: dial tcp: connection refused (proxy) in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 293 views

This error occurs when Docker cannot connect through your corporate or system proxy. The proxy server is either not running, not accessible, or requires authentication credentials that are not configured correctly in Docker.

Quick fix

Fixes proxyconnect tcp: dial tcp: connection refused (proxy)

echo "HTTP_PROXY: $HTTP_PROXY"
echo "HTTPS_PROXY: $HTTPS_PROXY"
echo "http_proxy: $http_proxy"
echo "https_proxy: $https_proxy"
echo "NO_PROXY: $NO_PROXY"

Identify the configured proxy settings
Clear proxy settings if not needed
Configure proxy with authentication
Configure Docker Desktop proxy settings

docker — error

$echo "HTTP_PROXY: $HTTP_PROXY"
echo "HTTPS_PROXY: $HTTPS_PROXY"
echo "http_proxy: $http_proxy"
echo "https_proxy: $https_proxy"
echo "NO_PROXY: $NO_PROXY"
proxyconnect tcp: dial tcp: connection refused (proxy)

What this error means

The "proxyconnect tcp: dial tcp: connection refused (proxy)" error indicates that Docker is trying to route traffic through a proxy server, but the connection to that proxy is failing. This typically happens when you're behind a corporate firewall or have proxy settings configured in your environment or Docker configuration. This error commonly manifests in several ways: - `Error response from daemon: Get "https://registry-1.docker.io/v2/": proxyconnect tcp: dial tcp 192.168.65.1:3128: connect: connection refused` - `proxyconnect tcp: dial tcp: lookup http: no such host` - `Proxy Authentication Required` The error can occur at multiple levels: - **Docker daemon level**: When the daemon itself needs to pull images through a proxy - **Docker client level**: When the CLI is configured to use a proxy - **Container level**: When containers try to access external resources through a proxy Common scenarios where this appears: - Corporate networks requiring authenticated proxy access - VPN connections that change network routing - Docker Desktop on Windows/macOS with proxy settings - CI/CD pipelines in enterprise environments - Misconfigured proxy environment variables from previous setups

Typical symptoms

Docker pull commands fail with 'proxyconnect tcp: connection refused'
Unable to download images from Docker Hub or other registries
Docker commands work on home network but fail at office/corporate network
Error mentions a proxy IP address like 192.168.65.1:3128 or 127.0.0.1:8080
Docker Desktop shows proxy-related errors in diagnostics
CI/CD pipelines fail with proxy authentication errors
Error appears after changing network or VPN connection

Common causes

Proxy server configured in Docker but not actually running
Proxy settings left over from previous network configuration
Corporate proxy requires authentication credentials not provided
Wrong proxy hostname or port in Docker configuration
Docker Desktop proxy settings conflict with system proxy
Environment variables HTTP_PROXY/HTTPS_PROXY pointing to unavailable proxy
VPN connection changed network routing and proxy availability
NTLM or Kerberos authentication required but not configured
Proxy server rejecting connections from Docker daemon
NO_PROXY not configured to bypass local or internal registries

How to fix "proxyconnect tcp: dial tcp: connection refused (proxy)"

1Identify the configured proxy settings

First, check what proxy settings Docker is using:

Check environment variables:

bash

echo "HTTP_PROXY: $HTTP_PROXY"
echo "HTTPS_PROXY: $HTTPS_PROXY"
echo "http_proxy: $http_proxy"
echo "https_proxy: $https_proxy"
echo "NO_PROXY: $NO_PROXY"

Check Docker client config:

bash

cat ~/.docker/config.json

Look for a "proxies" section:

json

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:3128",
      "httpsProxy": "http://proxy.example.com:3128"
    }
  }
}

Check Docker daemon config (Linux):

bash

cat /etc/docker/daemon.json
sudo systemctl show --property=Environment docker

Check Docker Desktop settings (Windows/macOS):
1. Open Docker Desktop
2. Go to Settings > Resources > Proxies
3. Note any configured proxy servers

2Clear proxy settings if not needed

If you're not behind a proxy (e.g., on home network), remove the proxy configuration:

Remove from Docker client config:
Edit ~/.docker/config.json and remove the "proxies" section, or delete the file if it only contains proxy settings:

bash

# Backup first
cp ~/.docker/config.json ~/.docker/config.json.backup

# Edit and remove proxies section
nano ~/.docker/config.json

Clear environment variables:

bash

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY no_proxy

To make this permanent, remove these variables from your shell config:

bash

# Check these files and remove proxy exports
~/.bashrc
~/.bash_profile
~/.zshrc
~/.profile
/etc/environment

Clear Docker Desktop proxy (Windows/macOS):
1. Open Docker Desktop
2. Go to Settings > Resources > Proxies
3. Uncheck "Manual proxy configuration"
4. Click "Apply & Restart"

For Linux daemon:

bash

# Remove proxy from daemon.json
sudo nano /etc/docker/daemon.json

# Remove systemd override if exists
sudo rm /etc/systemd/system/docker.service.d/http-proxy.conf
sudo systemctl daemon-reload
sudo systemctl restart docker

3Configure proxy with authentication

If you need to use a proxy with authentication, configure it properly:

Format for authenticated proxy:

bash

http://username:password@proxy.example.com:3128

Docker client configuration (~/.docker/config.json):

json

{
  "proxies": {
    "default": {
      "httpProxy": "http://username:password@proxy.example.com:3128",
      "httpsProxy": "http://username:password@proxy.example.com:3128",
      "noProxy": "localhost,127.0.0.1,.internal.company.com"
    }
  }
}

Special characters in password:
If your password contains special characters, URL-encode them:
- @ becomes %40
- : becomes %3A
- # becomes %23
- ! becomes %21

Example: Password p@ss:word! becomes p%40ss%3Aword%21

For systemd-managed Docker daemon (Linux):

bash

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf << EOF
[Service]
Environment="HTTP_PROXY=http://username:password@proxy.example.com:3128"
Environment="HTTPS_PROXY=http://username:password@proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1,.internal.company.com"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Verify configuration:

bash

sudo systemctl show --property=Environment docker
docker info | grep -i proxy

4Configure Docker Desktop proxy settings

For Docker Desktop on Windows or macOS:

Manual proxy configuration:
1. Open Docker Desktop
2. Click the gear icon (Settings)
3. Navigate to Resources > Proxies
4. Enable "Manual proxy configuration"
5. Enter your proxy details:
- Web Server (HTTP): http://proxy.example.com:3128
- Secure Web Server (HTTPS): http://proxy.example.com:3128
- Bypass proxy for: localhost,127.0.0.1,.internal.company.com
6. Click "Apply & Restart"

Use system proxy (recommended for corporate environments):
1. Open Docker Desktop Settings
2. Go to Resources > Proxies
3. Select "Use system proxy"
4. Apply & Restart

This will automatically use the proxy settings configured in Windows Internet Options or macOS System Preferences.

Verify Docker Desktop can reach the registry:
1. Open Docker Desktop
2. Go to Troubleshoot (bug icon)
3. Click "Run Diagnostics"
4. Check for proxy-related errors

5Test proxy connectivity directly

Before configuring Docker, verify the proxy is accessible:

Test with curl:

bash

# Test proxy without authentication
curl -v -x http://proxy.example.com:3128 https://registry-1.docker.io/v2/

# Test proxy with authentication
curl -v -x http://username:password@proxy.example.com:3128 https://registry-1.docker.io/v2/

# Test if proxy is reachable at all
nc -zv proxy.example.com 3128
telnet proxy.example.com 3128

Test with wget:

bash

https_proxy=http://proxy.example.com:3128 wget -O- https://registry-1.docker.io/v2/

Common proxy ports to check:
- 3128: Squid default
- 8080: Common HTTP proxy port
- 8888: Alternative proxy port
- 80: Some transparent proxies

If the proxy test fails, contact your network administrator to:
- Verify the correct proxy hostname and port
- Get valid authentication credentials
- Check if your machine's IP is allowed to use the proxy

6Handle NTLM authentication proxies

Corporate proxies often use NTLM (Windows authentication), which Docker doesn't natively support. Use a local proxy bridge:

Option 1: Cntlm (recommended)

Install and configure cntlm:

bash

# Install cntlm
# Ubuntu/Debian
sudo apt-get install cntlm

# macOS
brew install cntlm

# Configure cntlm
sudo nano /etc/cntlm.conf

Add your configuration:

bash

Username    your_username
Domain      YOUR_DOMAIN
Proxy       proxy.company.com:3128
Listen      3128

Generate password hash:

bash

cntlm -H -d YOUR_DOMAIN -u your_username
# Enter password when prompted
# Copy the PassNTLMv2 line to /etc/cntlm.conf

Start cntlm:

bash

sudo systemctl start cntlm
sudo systemctl enable cntlm

Configure Docker to use local cntlm:

bash

# Now proxy through localhost:3128
export HTTP_PROXY=http://localhost:3128
export HTTPS_PROXY=http://localhost:3128

Option 2: Px proxy (Python-based)

bash

pip install px-proxy
px --proxy=proxy.company.com:3128 --listen=3128

Then configure Docker to use http://localhost:3128

7Configure NO_PROXY for internal registries

Ensure internal registries and local addresses bypass the proxy:

Set NO_PROXY correctly:

bash

export NO_PROXY="localhost,127.0.0.1,::1,.local,internal-registry.company.com,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"

In Docker config.json:

json

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:3128",
      "httpsProxy": "http://proxy.example.com:3128",
      "noProxy": "localhost,127.0.0.1,::1,.local,.internal.company.com,internal-registry.company.com,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
    }
  }
}

For Docker daemon on Linux:

bash

sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf << EOF
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:3128"
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1,.internal.company.com,10.0.0.0/8"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Important NO_PROXY patterns:
- .company.com - matches any subdomain
- company.com - matches exact domain only
- 10.0.0.0/8 - matches entire IP range (may not work in all contexts)
- * - bypass proxy entirely (useful for testing)

8Restart Docker and test

After configuring proxy settings, restart Docker completely:

Linux:

bash

sudo systemctl restart docker
# Verify Docker is running
sudo systemctl status docker

Docker Desktop (Windows/macOS):
1. Click Docker icon in system tray
2. Select "Restart"
Or use the command line:

bash

# macOS
killall Docker && open -a Docker

# Windows PowerShell
Stop-Process -Name "Docker Desktop" -Force
Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"

Test connectivity:

bash

# Test docker pull
docker pull hello-world

# Test with verbose output
docker pull alpine --debug

# Check if proxy is being used
docker info | grep -i proxy

If still failing, check daemon logs:

bash

# Linux
sudo journalctl -u docker.service -f

# Docker Desktop
# View logs from Troubleshoot > Get Support > Diagnose & Feedback

Advanced notes

Understanding Docker's proxy configuration levels:

Docker proxy settings can be configured at multiple levels, which can lead to confusion:

1. Docker daemon - Used for image pulls and registry communication
2. Docker client - Used for CLI operations and passed to containers
3. Build-time - ARG/ENV in Dockerfile for build operations
4. Container runtime - Environment variables in running containers

Each level may need separate configuration in enterprise environments.

Debugging proxy issues:

Enable Docker daemon debug mode:

bash

# Add to /etc/docker/daemon.json
{
  "debug": true
}

# Or start dockerd with debug flag
dockerd --debug

View detailed proxy negotiation:

bash

curl -v --proxy-verbose -x http://proxy:3128 https://registry-1.docker.io/v2/

VPN and proxy conflicts:

When connected to a corporate VPN:
- The VPN may change default routes, making the proxy unreachable
- Split tunneling settings may affect proxy connectivity
- DNS resolution for proxy hostname may fail

Solutions:
1. Use proxy IP address instead of hostname
2. Configure VPN split tunneling to allow proxy traffic
3. Use a local proxy bridge (cntlm/px) that's started before VPN

Docker Desktop and WSL2 proxy issues:

On Windows with WSL2:

bash

# Check if WSL2 can reach the proxy
curl -v -x http://proxy.company.com:3128 https://google.com

# If proxy is on Windows host, use host.docker.internal
export HTTP_PROXY=http://host.docker.internal:3128

Certificate issues with proxy:

If the proxy performs SSL inspection (man-in-the-middle):

bash

# Add corporate CA certificate
sudo cp company-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# For Docker daemon, add to daemon.json
{
  "insecure-registries": ["registry.company.com"]
}

# For containers, mount certificates
docker run -v /etc/ssl/certs:/etc/ssl/certs:ro myimage

Temporary bypass for testing:

To test without proxy:

bash

# Unset all proxy variables temporarily
env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy docker pull alpine

# Or set to empty
HTTP_PROXY= HTTPS_PROXY= docker pull alpine

Frequently asked questions

What does "proxyconnect tcp: dial tcp: connection refused (proxy)" mean?: The "proxyconnect tcp: dial tcp: connection refused (proxy)" error indicates that Docker is trying to route traffic through a proxy server, but the connection to that proxy is failing. This typically happens when you're behind a corporate firewall or have proxy settings configured in your environment or Docker configuration.
How do I fix "proxyconnect tcp: dial tcp: connection refused (proxy)"?: This error occurs when Docker cannot connect through your corporate or system proxy. The proxy server is either not running, not accessible, or requires authentication credentials that are not configured correctly in Docker.
What causes "proxyconnect tcp: dial tcp: connection refused (proxy)"?: Proxy server configured in Docker but not actually running Proxy settings left over from previous network configuration Corporate proxy requires authentication credentials not provided
Is the "proxyconnect tcp: dial tcp: connection refused (proxy)" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Docker Official Documentation
📖
Proxy configuration - Docker Docs(Official Docs)
📖
Daemon proxy configuration - Docker Docs(Official Docs)
💬
proxyconnect tcp: dial tcp connection refused - Stack Overflow(Stack Overflow)
💬
Getting past proxy: Authentication required - Docker Forums(Stack Overflow)
🐙
proxyconnect tcp: dial tcp: connection refused - GitHub Issue(GitHub)
🐙
proxyconnect tcp error response from daemon - GitHub Issue(GitHub)
🐙
proxyconnect with experimental features enabled - GitHub Issue(GitHub)
📖
Configuring a Proxy in Docker - Baeldung(Official Docs)
📖
100 Common Docker Errors and Solutions - DEV Community(Official Docs)

How to fix proxyconnect tcp: dial tcp: connection refused (proxy) in Docker

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "proxyconnect tcp: dial tcp: connection refused (proxy)"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading