Windows Server 2019 — Chocolatey package install fails due to TLS 1.2 handshake error — 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

choco install commands fail on Windows Server 2019 with TLS handshake errors, blocking deployment of community packages.

Environment & Reproduction

Triggered when PowerShell defaults to TLS 1.0 or 1.1 while the Chocolatey community feed enforces TLS 1.2 minimum.

choco install git -y
[Net.ServicePointManager]::SecurityProtocol

Root Cause Analysis

Legacy .NET Framework defaults negotiate weak TLS that the remote endpoint rejects, leaving the package download incomplete.

Quick Triage

Validate current TLS policy and test the feed endpoint reachability.

Get-ItemProperty 'HKLM:SOFTWAREMicrosoft.NETFrameworkv4.0.30319'
Test-NetConnection community.chocolatey.org -Port 443

Step-by-Step Diagnosis

Capture protocol negotiation details using Invoke-WebRequest with explicit protocol.

[Net.ServicePointManager]::SecurityProtocol = 'Tls12'
Invoke-WebRequest https://community.chocolatey.org/api/v2/ -UseBasicParsing

Solution — Primary Fix

Enable strong cryptography for .NET Framework and persist TLS 1.2 as default for outbound requests.

Set-ItemProperty 'HKLM:SOFTWAREMicrosoft.NETFrameworkv4.0.30319' SchUseStrongCrypto 1 -Type DWord
Set-ItemProperty 'HKLM:SOFTWAREWOW6432NodeMicrosoft.NETFrameworkv4.0.30319' SchUseStrongCrypto 1 -Type DWord

Solution — Alternative Approaches

Pre-download the .nupkg file from an internal mirror and install with –source pointing locally.

choco install git --source 'C:choco-cache;https://community.chocolatey.org/api/v2/'

Verification & Acceptance Criteria

Package downloads complete without protocol errors and install successfully.

choco list --local-only
choco install git -y

Rollback Plan

Revert SchUseStrongCrypto registry edits if legacy apps require older TLS during transition.

Remove-ItemProperty 'HKLM:SOFTWAREMicrosoft.NETFrameworkv4.0.30319' SchUseStrongCrypto

Prevention & Hardening

Standardise TLS 1.2 enforcement across servers and audit cipher suite configuration regularly.

Get-TlsCipherSuite | Sort Name

Related Errors & Cross-Refs

Related: NuGet feed reachability errors, expired root CA chains, and proxy interception breaking certificate validation.

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

View all Windows Server 2019 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Microsoft Learn guidance on TLS 1.2 enablement for .NET Framework and Chocolatey installation prerequisites.