How to Fix Docker’s “x509:Unknown Authority” Error

---

You’re all set to pull a new image, maybe from ghcr.io or another private registry. You type docker pull… and then, bam.

Error response from daemon: Get "https://ghcr.io/v2/": x509: certificate signed by unknown authority

If you’ve hit this roadblock, take a deep breath. You’re not alone, and your command is probably correct. This isn’t a bug in your code; it’s a classic battle between Docker and a very common security setup. The Docker x509 certificate error is almost always a sign that you’re on a corporate or institutional network, and we’re going to fix it.

---

The “Why”: Corporate Proxies & SSL Inspection

So what’s really happening here?

In simple terms: your network is intercepting your traffic.

Most company networks use a security appliance—a proxy or firewall (like Zscaler, for example)—to inspect all web traffic for malware or data leaks. To inspect encrypted (SSL/TLS) traffic, this proxy has to do something clever:

1. It stops your request to ghcr.io.
2. It decrypts the request and scans it.
3. It then re-encrypts the traffic and sends it to you, but with a catch: it uses its own SSL certificate, not the real one from ghcr.io.

This internal certificate is signed by your company’s own “Certificate Authority” (CA).

Your IT department has already configured your web browsers (like Chrome and Firefox) to trust this internal CA. That’s why you can browse HTTPS sites without seeing a million warnings.

Docker, however, is not your browser. The Docker daemon has its own trust store, and it has not been told to trust your company’s private certificate. When it connects to ghcr.io and sees a certificate from “Some Random Proxy CA” instead of “GitHub,” it correctly throws a security error and aborts the connection.

Here are the two ways to fix this. Solution 1 is the right, secure, and permanent method.

---

Solution 1: Add the Trust Certificate (The Right Way)

The best solution is to simply tell your Docker daemon to trust your company’s internal CA, just like your browser does.

Step 1: Obtain the CA Certificate

First, you need the root CA certificate file (usually a .crt or .pem file) from your company.

• The Easy Way: Ask your IT or network security department for the “root proxy CA certificate.”
• The Browser Way: You can often export it from your browser.
  1. In your browser (on the same machine), go to https://ghcr.io.
  2. Click the padlock icon next to the URL.
  3. View the certificate details (this varies by browser, but look for “Certificate is valid” or “Connection is secure”).
  4. Find the Certification Path or Certificate Chain tab.
  5. The top-most certificate in the list is the root CA. It will likely be the name of your company or its security software.
  6. Select that root certificate and find the “Export” or “Download” option (often under “Details”). Save it as a .crt file.

Step 2: Add the Certificate to Docker (Linux)

Docker on Linux looks for certificates in a dedicated folder. You must create a new directory named after the host you’re trying to reach.

First, create the directory for the ghcr.io registry:

Bash

sudo mkdir -p /etc/docker/certs.d/ghcr.io

Next, copy your certificate file into that directory and—this is important—rename it to ca.crt:

Bash

sudo cp /path/to/your/company_ca.crt /etc/docker/certs.d/ghcr.io/ca.crt

Step 3: Restart the Docker Daemon

Docker needs to be restarted to load the new certificate.

Bash

sudo systemctl restart docker

Try your docker pull command again. It should now work perfectly.

---

Solution 2: The “Insecure-Registries” Fix (The Risky Way)

This solution tells Docker, “Don’t bother verifying the certificate for ghcr.io.”

Warning: This is a major security risk. It completely disables TLS verification for this registry, making you vulnerable to man-in-the-middle attacks. Only use this as a temporary fix in a trusted, isolated environment, and never on a production server.

Step 1: Edit the Docker daemon.json File

Open or create the Docker daemon’s configuration file, usually located at /etc/docker/daemon.json.

Bash

sudo nano /etc/docker/daemon.json

Add the insecure-registries key. If the file is empty, add this:

JSON

{
  "insecure-registries": ["ghcr.io"]
}

If the file already has other settings, just add the new line (and be careful with the commas):

JSON

{
  "some-other-key": "value",
  "insecure-registries": ["ghcr.io"]
}

Step 2: Restart the Docker Daemon

You must restart Docker for the changes to take effect.

Bash

sudo systemctl restart docker

This will “work,” but you’ve punched a security hole in your setup. We really recommend you use Solution 1.

---

What About Docker Desktop (Windows/Mac)?

If you’re using Docker Desktop, the instructions above for /etc/docker/ will not work. Docker Desktop has its own way of managing certificates.

The good news is it’s often easier.

• On macOS: Docker Desktop for Mac automatically uses the operating system’s built-in Keychain.
  1. Get the .crt or .pem file from your IT department.
  2. Open the Keychain Access app.
  3. Drag your certificate file into the System keychain.
  4. Double-click the newly added certificate, expand the “Trust” section, and set “When using this certificate” to “Always Trust”.
  5. Restart Docker Desktop.
• On Windows: Docker Desktop for Windows uses the Windows Certificate Store.
  1. Get the .crt file.
  2. Right-click the file and select “Install Certificate”.
  3. Choose Store Location: “Local Machine”.
  4. In the next step, select “Place all certificates in the following store” and browse.
  5. Select the “Trusted Root Certification Authorities” store.
  6. Click Finish and restart Docker Desktop.

For more details, check out Docker’s official documentation on insecure registries and CAs.

---

Conclusion: Back to Pulling Images

That frustrating Docker x509 certificate error is almost never about Docker itself, but how it interacts with a secured network.

By adding your company’s root CA to your system’s trust store (Solution 1), you’re creating a permanent, secure fix that acknowledges your network’s security policy without compromising your own. It might take an extra five minutes, but it’s the professional and correct way to solve the problem.

Now, go pull that image.

---

Sources

• Docker Docs: Verify repository client with certificates
• How to Export a Root CA Certificate from a Browser