How to fix x509: certificate signed by unknown authority in Docker

DockerINTERMEDIATEMEDIUM

This error occurs when Docker cannot verify the SSL/TLS certificate of a registry or server. It typically happens with private registries using self-signed certificates, corporate proxies that intercept HTTPS traffic, or when the CA certificate is not installed on the Docker host.

What this error means

The "x509: certificate signed by unknown authority" error appears when Docker's TLS verification fails because it cannot find a trusted Certificate Authority (CA) that signed the certificate presented by the registry or server. Docker relies on secure HTTPS connections to verify the authenticity and integrity of container images. This commonly happens in several scenarios: - **Private registries** using self-signed certificates that aren't in Docker's trust store - **Corporate environments** where proxy servers intercept HTTPS traffic and re-sign certificates with their own CA - **Air-gapped environments** where internal CAs are used for security compliance - **Misconfigured certificate chains** where intermediate certificates are missing The x509 package in Go (which Docker uses) validates certificates against the system's CA certificate store and Docker's own certificate directory. When neither contains the signing CA, Docker refuses the connection to prevent potential man-in-the-middle attacks.

How to fix "x509: certificate signed by unknown authority"

1Add certificate to Docker's certs.d directory

The most direct fix is to place the CA certificate in Docker's certificate directory. This tells Docker to trust certificates signed by that CA for the specific registry:

bash

# Create the directory for your registry (include port if not 443)
sudo mkdir -p /etc/docker/certs.d/your-registry.example.com:5000

# Copy your CA certificate (must be named ca.crt)
sudo cp your-ca-certificate.crt /etc/docker/certs.d/your-registry.example.com:5000/ca.crt

# Restart Docker to apply changes
sudo systemctl restart docker

The directory name must match exactly how you reference the registry in your Docker commands:
- Registry at myregistry.com on port 443: /etc/docker/certs.d/myregistry.com/ca.crt
- Registry at myregistry.com:5000: /etc/docker/certs.d/myregistry.com:5000/ca.crt

2Add certificate to the system CA store

Adding the certificate to your operating system's CA store makes it trusted system-wide, including by Docker:

Ubuntu/Debian:

bash

# Copy certificate to system CA directory
sudo cp your-ca-certificate.crt /usr/local/share/ca-certificates/

# Update CA certificates
sudo update-ca-certificates

# Restart Docker
sudo systemctl restart docker

RHEL/CentOS/Fedora:

bash

# Copy certificate to CA trust directory
sudo cp your-ca-certificate.crt /etc/pki/ca-trust/source/anchors/

# Update CA trust
sudo update-ca-trust

# Restart Docker
sudo systemctl restart docker

OpenSUSE:

bash

# Copy certificate
sudo cp your-ca-certificate.crt /etc/pki/trust/anchors/

# Update certificates
sudo update-ca-certificates

# Restart Docker
sudo systemctl restart docker

3Extract the certificate from the registry

If you don't have the CA certificate file, you can extract it directly from the registry:

bash

# Extract certificate from the registry
openssl s_client -showcerts -connect your-registry.example.com:443 </dev/null 2>/dev/null | \
  openssl x509 -outform PEM > registry-cert.crt

# View certificate details to verify
openssl x509 -in registry-cert.crt -text -noout | head -20

# For registries with multiple certificates in the chain,
# save all of them (intermediate + root)
openssl s_client -showcerts -connect your-registry.example.com:443 </dev/null 2>/dev/null | \
  awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/{ print }' > full-chain.crt

After extracting, place the certificate in Docker's certs.d directory or the system CA store as shown in previous steps.

4Configure insecure registry (development only)

For development or testing environments where certificate management isn't critical, you can configure Docker to skip TLS verification for specific registries:

bash

# Edit or create Docker daemon configuration
sudo nano /etc/docker/daemon.json

Add your registry to the insecure-registries list:

json

{
  "insecure-registries": ["your-registry.example.com:5000"]
}

Then restart Docker:

bash

sudo systemctl restart docker

Warning: This disables TLS verification entirely for the specified registry. Never use this in production as it makes you vulnerable to man-in-the-middle attacks. Only use for:
- Local development registries
- Temporary testing scenarios
- Isolated networks with no external access

5Fix corporate proxy certificate issues

In corporate environments, security appliances often intercept HTTPS traffic and re-sign certificates. You need to install the corporate root CA certificate:

1. Obtain your corporate CA certificate - Contact your IT department or security team

2. For Docker on Linux:

bash

# Add corporate CA to system store
sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
sudo systemctl restart docker

3. For Docker Desktop on Windows:
- Export the corporate CA from Windows Certificate Manager
- Open Docker Desktop Settings > Docker Engine
- Or place certificate in %USERPROFILE%\.docker\certs.d\<registry>

4. For Docker Desktop on macOS:
- Add certificate to Keychain Access
- Mark it as "Always Trust"
- Restart Docker Desktop

5. Verify proxy is the issue:

bash

# Check if proxy is intercepting certificates
curl -v https://registry-1.docker.io 2>&1 | grep -i "issuer"
# If issuer is your company name instead of DigiCert/Amazon/etc., proxy is intercepting

6Restart Docker after certificate changes

Docker caches certificate information, so you must restart the Docker daemon after any certificate changes:

bash

# Linux with systemd
sudo systemctl restart docker

# Linux with SysVinit
sudo service docker restart

# Verify Docker is running
docker info

# Test registry connection
docker pull your-registry.example.com:5000/test-image

Docker Desktop (Windows/macOS):
1. Right-click Docker icon in system tray
2. Select "Restart"
3. Or quit and reopen Docker Desktop

If the error persists after restart, verify the certificate is in the correct location:

bash

# Check Docker's certificate directory
ls -la /etc/docker/certs.d/

# Check system CA certificates were updated
ls -la /etc/ssl/certs/ | grep your-cert-name

How to fix x509: certificate signed by unknown authority in Docker

What this error means

Typical symptoms

Common causes

How to fix "x509: certificate signed by unknown authority"

Advanced notes

Related errors

Official resources & further reading