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.
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
First, check what proxy settings Docker is using:
Check environment variables:
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:
cat ~/.docker/config.jsonLook for a "proxies" section:
{
"proxies": {
"default": {
"httpProxy": "http://proxy.example.com:3128",
"httpsProxy": "http://proxy.example.com:3128"
}
}
}Check Docker daemon config (Linux):
cat /etc/docker/daemon.json
sudo systemctl show --property=Environment dockerCheck Docker Desktop settings (Windows/macOS):
1. Open Docker Desktop
2. Go to Settings > Resources > Proxies
3. Note any configured proxy servers
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:
# Backup first
cp ~/.docker/config.json ~/.docker/config.json.backup
# Edit and remove proxies section
nano ~/.docker/config.jsonClear environment variables:
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY no_proxyTo make this permanent, remove these variables from your shell config:
# Check these files and remove proxy exports
~/.bashrc
~/.bash_profile
~/.zshrc
~/.profile
/etc/environmentClear 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:
# 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 dockerIf you need to use a proxy with authentication, configure it properly:
Format for authenticated proxy:
http://username:[email protected]:3128Docker client configuration (~/.docker/config.json):
{
"proxies": {
"default": {
"httpProxy": "http://username:[email protected]:3128",
"httpsProxy": "http://username:[email protected]: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):
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:[email protected]:3128"
Environment="HTTPS_PROXY=http://username:[email protected]:3128"
Environment="NO_PROXY=localhost,127.0.0.1,.internal.company.com"
EOF
sudo systemctl daemon-reload
sudo systemctl restart dockerVerify configuration:
sudo systemctl show --property=Environment docker
docker info | grep -i proxyFor 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
Before configuring Docker, verify the proxy is accessible:
Test with curl:
# 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:[email protected]:3128 https://registry-1.docker.io/v2/
# Test if proxy is reachable at all
nc -zv proxy.example.com 3128
telnet proxy.example.com 3128Test with wget:
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
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:
# Install cntlm
# Ubuntu/Debian
sudo apt-get install cntlm
# macOS
brew install cntlm
# Configure cntlm
sudo nano /etc/cntlm.confAdd your configuration:
Username your_username
Domain YOUR_DOMAIN
Proxy proxy.company.com:3128
Listen 3128Generate password hash:
cntlm -H -d YOUR_DOMAIN -u your_username
# Enter password when prompted
# Copy the PassNTLMv2 line to /etc/cntlm.confStart cntlm:
sudo systemctl start cntlm
sudo systemctl enable cntlmConfigure Docker to use local cntlm:
# Now proxy through localhost:3128
export HTTP_PROXY=http://localhost:3128
export HTTPS_PROXY=http://localhost:3128Option 2: Px proxy (Python-based)
pip install px-proxy
px --proxy=proxy.company.com:3128 --listen=3128Then configure Docker to use http://localhost:3128
Ensure internal registries and local addresses bypass the proxy:
Set NO_PROXY correctly:
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:
{
"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:
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 dockerImportant 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)
After configuring proxy settings, restart Docker completely:
Linux:
sudo systemctl restart docker
# Verify Docker is running
sudo systemctl status dockerDocker Desktop (Windows/macOS):
1. Click Docker icon in system tray
2. Select "Restart"
Or use the command line:
# 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:
# 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 proxyIf still failing, check daemon logs:
# Linux
sudo journalctl -u docker.service -f
# Docker Desktop
# View logs from Troubleshoot > Get Support > Diagnose & FeedbackUnderstanding 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:
# Add to /etc/docker/daemon.json
{
"debug": true
}
# Or start dockerd with debug flag
dockerd --debugView detailed proxy negotiation:
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:
# 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:3128Certificate issues with proxy:
If the proxy performs SSL inspection (man-in-the-middle):
# 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 myimageTemporary bypass for testing:
To test without proxy:
# 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 alpineimage operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub