Ubuntu 22.04 LTS Docker Pull Fails with x509 Certificate Signed by Unknown Authority

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Container deployments fail because docker pull cannot verify registry certificate. CI/CD pipelines halt and runtime scaling operations cannot fetch required images.

Environment & Reproduction

Ubuntu 22.04 LTS host uses Docker Engine with private registry behind enterprise PKI or SSL inspection proxy. Reproduce by pulling image from registry with unknown CA.

Root Cause Analysis

Docker daemon relies on host trust store and registry-specific cert paths. Missing root/intermediate CA files or broken chain presentation leads to x509 verification failure.

Quick Triage

Confirm certificate path and registry URL, then inspect presented chain using openssl before changing daemon security settings.

Step-by-Step Diagnosis

Check CA installation status in system trust store and Docker cert directory. Validate chain includes required intermediates and that hostname matches certificate SAN entries.

Solution – Primary Fix

Install enterprise CA certificate into Ubuntu trust store and registry-specific Docker path, then restart Docker daemon and retry image pull.

Solution – Alternative Approaches

Use registry mirrors with trusted public CA, issue certificates from approved internal PKI chain, or switch to token-authenticated registry endpoints with valid chain.

Verification & Acceptance Criteria

docker pull succeeds consistently, no x509 errors in daemon logs, and deployment automation completes image fetch stage without manual intervention.

Rollback Plan

Remove newly added CA files if incorrect, run update-ca-certificates to restore previous trust set, and restart Docker daemon to return baseline behavior.

Prevention & Hardening

Standardize registry certificates, monitor expiration windows, and automate CA distribution to all Ubuntu 22.04 container hosts via configuration management.

Related Errors & Cross-Refs

Related to proxy CONNECT failures, DNS name mismatch, and stale cached certificates after registry certificate rotation.

Related tutorial: View the step-by-step tutorial for Ubuntu 22.04 LTS.

View all Ubuntu 22.04 LTS tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

See Docker registry security docs, Ubuntu CA trust management documentation, and man pages for update-ca-certificates(8) and openssl(1).