Fix: Docker Desktop 407 Proxy Authentication Errors

In corporate enterprise environments, Docker Desktop often operates behind a Secure Web Gateway (SWG) or an NTLM/Kerberos proxy. While Docker Desktop provides a UI for proxy settings, authentication often fails because the underlying Linux VM (WSL2 or Hyper-V) cannot propagate credentials correctly or lacks the necessary CA certificates for SSL inspection.

The Error Log

When attempting a docker pull or docker build, the daemon returns one of the following traces:

Error response from daemon: Get "https://registry-1.docker.io/v2/": proxyconnect tcp: dial tcp: lookup <proxy-host>: no such host

Or, more commonly in authenticated environments:

Error response from daemon: Get "https://registry-1.docker.io/v2/": Forbidden (407 Proxy Authentication Required)
# Or for SSL Inspection issues:
Error response from daemon: Get "https://registry-1.docker.io/v2/": x509: certificate signed by unknown authority

Diagnostic Checklist

1. Credential Format: Are you using the http://user:password@proxy:port format? Special characters in passwords (e.g., @, #, !) must be URL-encoded.
2. System Environment: Run echo $HTTP_PROXY (macOS/Linux) or [System.Environment]::GetEnvironmentVariable("HTTP_PROXY") (PowerShell) to check if the host OS matches Docker’s internal settings.
3. WSL2 Connectivity: If using Windows, check if ping google.com works inside your WSL2 distribution. Often, the resolv.conf is overwritten, breaking DNS lookup for the proxy host.
4. SSL Inspection: Is your company using a tool like Zscaler or Fortinet? These require injecting a custom Root CA into the Docker Desktop engine.

The Fix

1. Configure Docker Desktop Engine

The UI settings are often insufficient. You must manually define the proxy configuration in the settings.json (or via the UI “Resources > Proxies” tab) using URL-encoded credentials.

If your password is P@ssword123, encode it to P%40ssword123.

{
  "proxies": {
    "default": {
      "httpProxy": "http://domain%5Cuser:P%[email protected]:8080",
      "httpsProxy": "http://domain%5Cuser:P%[email protected]:8080",
      "noProxy": "localhost,127.0.0.1,.corporate.local,169.254.169.254"
    }
  }
}

2. Inject Corporate CA Certificates (SSL Inspection)

If you see x509: certificate signed by unknown authority, the Docker VM doesn’t trust your proxy’s SSL interceptor.

For Windows (WSL2):

1. Export your corporate Root CA as a .crt file.
2. Place it in the Docker config directory: %USERPROFILE%\.docker\certs.d\registry-1.docker.io\ca.crt
3. Restart Docker Desktop.

For macOS: Add the certificate to the macOS Keychain (System login) and ensure it is marked as “Always Trust.” Docker Desktop for Mac automatically pulls certificates from the Keychain.

3. Update Runtime Environment Variables

For docker build operations, the proxy must be passed as build arguments or defined in the Dockerfile to allow the container to fetch packages (like apt-get or npm install).

In docker-compose.yaml:

services:
  app:
    build:
      context: .
      args:
        - http_proxy=${HTTP_PROXY}
        - https_proxy=${HTTPS_PROXY}
        - no_proxy=${NO_PROXY}

In Dockerfile:

FROM node:18
ARG http_proxy
ARG https_proxy

# Set environment variables for the build process
ENV http_proxy=$http_proxy
ENV https_proxy=$https_proxy

RUN npm install

4. Fix WSL2 DNS (Windows Specific)

If the proxy host cannot be resolved, prevent WSL2 from auto-generating resolv.conf which often points to an unreachable internal nameserver.

Create/Edit /etc/wsl.conf inside your WSL2 distro:

[network]
generateResolvConf = false

Then, manually set your nameserver in /etc/resolv.conf:

nameserver 8.8.8.8

Finally, restart WSL via PowerShell: wsl --shutdown.