Solved: Docker SSL Handshake Failed with AWS ECR (2025)
Quick Fix Summary
TL;DRUpdate your Docker daemon's trusted CA certificates and renew your AWS ECR login token immediately.
The Docker client cannot establish a secure TLS connection to the AWS ECR registry, typically due to expired credentials or missing/outdated CA certificates. This prevents all image operations, halting deployments and causing pod failures.
Diagnosis & Causes
Recovery Steps
Step 1: Force Renew AWS ECR Credentials
AWS ECR tokens are valid for 12 hours. An expired token is the most common cause. Force a fresh authentication.
# Get new ECR token and login
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.comStep 2: Update System and Docker CA Certificates
The Docker daemon uses the host's CA certificate store. Update it and restart Docker to pick up new certificates.
# Update system CA certificates (Ubuntu/Debian)
sudo apt update && \
sudo apt install -y ca-certificates
# Update system CA certificates (RHEL/CentOS/Alma)
sudo yum update -y ca-certificates
# Restart Docker to use updated certs
sudo systemctl restart dockerStep 3: Verify System Time and Timezone
SSL/TLS validation is time-sensitive. A skewed system clock will cause handshake failures.
# Check current system time and sync if needed
date
# Install and sync with NTP (Ubuntu/Debian)
sudo apt install -y chrony && \
sudo chronyc makestep
# Install and sync with NTP (RHEL-based)
sudo yum install -y chrony && \
sudo chronyc makestepStep 4: Configure Docker Daemon with Explicit CA Trust (Advanced)
If behind a corporate proxy with a custom CA, explicitly configure the Docker daemon to trust it.
# Place your corporate CA cert in Docker's certs directory
sudo cp your-corporate-ca.crt /etc/docker/certs.d/123456789.dkr.ecr.us-east-1.amazonaws.com/
# Or place it in the global trusted CA directory for all registries
sudo cp your-corporate-ca.crt /usr/local/share/ca-certificates/&& sudo update-ca-certificates
# Restart Docker
sudo systemctl restart dockerStep 5: Test the SSL/TLS Connection Directly
Isolate the issue by testing the connection to ECR using openssl, bypassing Docker.
# Test basic SSL connectivity to ECR endpoint
openssl s_client -connect 123456789.dkr.ecr.us-east-1.amazonaws.com:443 -showcerts < /dev/null 2>&1 | head -30Architect's Pro Tip
"In CI/CD pipelines, always run 'docker logout' before logging in to ECR. Cached, stale credentials in ~/.docker/config.json often cause silent, intermittent handshake failures."
Frequently Asked Questions
Why does this error happen suddenly in my CI/CD pipeline that was working yesterday?
Most likely, the AWS ECR authentication token stored in your pipeline's environment expired (they last 12 hours). Your pipeline needs to execute the 'aws ecr get-login-password' command as a fresh step before every Docker pull/push.
I'm behind a corporate proxy. Which solution step is most critical?
Step 4 is essential. You must obtain your company's internal Root CA certificate and install it into the host's trust store and Docker's specific directory. Without this, all SSL traffic to external registries like ECR will be blocked.
Does restarting Docker daemon cause downtime?
Yes. A restart temporarily halts all container operations. In production, schedule this during a maintenance window or perform a rolling restart across your node cluster. For a single node, this is a critical but necessary recovery step.