Windows Server 2022 — Windows container image pulls fail with TLS handshake timeout — Fix & Prevention

📖 ~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

`docker pull` fails and deployment pipelines stop on image retrieval.

Environment & Reproduction

Seen behind strict egress filtering, proxy interception, or incorrect MTU paths.

docker pull mcr.microsoft.com/windows/servercore:ltsc2022

Root Cause Analysis

TLS session negotiation to registry endpoints is interrupted by firewall, proxy, or cert trust problems.

Quick Triage

Test registry reachability and DNS resolution.

Test-NetConnection mcr.microsoft.com -Port 443
Resolve-DnsName mcr.microsoft.com

Step-by-Step Diagnosis

Capture daemon logs and proxy settings.

Get-Content C:ProgramDatadockerconfigdaemon.json -ErrorAction SilentlyContinue

Solution — Primary Fix

Allow required endpoints/ports, set proxy correctly, and refresh trusted roots.

setx HTTP_PROXY http://proxy:8080
setx HTTPS_PROXY http://proxy:8080
Restart-Service docker

Solution — Alternative Approaches

Mirror images in internal registry to avoid external pulls during runtime.

docker tag mcr.microsoft.com/windows/servercore:ltsc2022 registry.local/servercore:ltsc2022
docker push registry.local/servercore:ltsc2022

Verification & Acceptance Criteria

Image pull completes within SLA and no TLS timeout appears.

docker pull registry.local/servercore:ltsc2022

Rollback Plan

Revert proxy/env changes and restore previous daemon config.

[Environment]::SetEnvironmentVariable('HTTP_PROXY',$null,'Machine')

Prevention & Hardening

Maintain allowlist of container registry endpoints and monitor TLS errors.

Get-WinEvent -LogName Application -MaxEvents 100 | ? Message -match 'TLS|timeout'

Related Errors & Cross-Refs

Related: DNS NXDOMAIN for registry endpoints and HTTP 407 proxy auth failures.

Related tutorial: View the step-by-step tutorial for Windows Server 2022.

View all Windows Server 2022 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Microsoft and Docker documentation for Windows registry connectivity and proxy configuration.