Troubleshooting and Resolving TLS Handshake Errors for `git pull` Failures in WSL2

Troubleshooting and Resolving TLS Handshake Errors for `git pull` in WSL2#

When performing a git pull operation in a WSL2 environment, you may encounter connection errors caused by TLS/SSL handshake failures. Common error messages include gnutls_handshake() failed: The TLS connection was non-properly terminated. or OpenSSL SSL_connect: SSL_ERROR_SYSCALL. Such issues are often related to network proxies, SSL certificate trust chains, or compatibility with underlying TLS libraries.

Problem Identification#

The error message directly indicates an abnormal termination of the TLS/SSL handshake process. Before delving deeper, it is advisable to conduct basic connectivity and configuration checks:

System Time Synchronization: Verify that the WSL2 system time is consistent with the actual time using the date -R command. Time desynchronization may lead to certificate validation failures.
Network Reachability: Use ping your-repo-domain.com to confirm that the target code repository domain can be resolved and is reachable.
Git Proxy Configuration: Execute git config --global http.proxy and git config --global https.proxy to check the global proxy settings for Git. If configurations exist, you may try temporarily removing them with git config --global --unset http.proxy.

If the basic checks show no anomalies and the issue persists, further analysis of the TLS handshake process is required. You can obtain detailed connection logs using the curl -v command:

curl -v https://your-repo-domain.com/path/to/repo.git/info/refs?service=git-upload-pack

If the curl -v output includes Uses proxy env variable https_proxy == 'http://X.X.X.X:YYYY' and the proxy connection is successful (CONNECT tunnel established, response 200), but ultimately fails due to OpenSSL SSL_connect: SSL_ERROR_SYSCALL, it strongly indicates that the proxy is intercepting TLS traffic. Proxies typically run on the Windows host and provide services through their IP address (e.g., the default gateway IP of WSL2). When such proxies intercept HTTPS traffic, they use their own generated SSL certificates as a man-in-the-middle, which WSL2 does not trust by default.

For instance, if the certificate issuer is shown as a non-publicly trusted entity (like WR2), it further confirms that proxy interception is the core issue.

Solution: Trust the Proxy Root Certificate#

The core solution is to make WSL2 trust the root certificate used by the proxy server.

Step 1: Obtain the Proxy Root Certificate#

Export the Certificate from the Windows Browser:
- In the Windows host browser, visit any HTTPS website (e.g., https://www.baidu.com).
- Click on the lock icon on the left side of the address bar to view certificate information.
- In the certificate path or certification path, look for the root certificate issued by a non-publicly trusted entity (like WR2).
- Select the certificate, click "View Certificate", and switch to the "Details" tab.
- Click the "Copy to File..." button and choose the "Base-64 encoded X.509 (.CER)" format.
- Save the file to the Windows Downloads folder, with a filename example: my_proxy_root.crt.

Step 2: Copy the Certificate to WSL2#

Assuming the Windows username is YourWindowsUsername:

cp "/mnt/c/Users/YourWindowsUsername/Downloads/my_proxy_root.crt" ~/

Step 3: Add the Certificate to WSL2 Trust Store#

sudo cp ~/my_proxy_root.crt /usr/local/share/ca-certificates/my_proxy_root.crt
sudo update-ca-certificates

After executing the update-ca-certificates command, the system will update its list of trusted certificates and report that the certificate has been successfully added.

Step 4: Verify and Retry Git Operation#

Ensure that the proxy environment variables are correctly set in the WSL2 session (e.g., https_proxy). If necessary, you can set them manually:

# Verify proxy environment variable
echo $https_proxy

# Set manually if necessary
# export https_proxy='http://[proxyIP]:[proxyPort]'
# export http_proxy='http://[proxyIP]:[proxyPort]'
# export no_proxy='localhost,127.0.0.1,::1,[internalIPRange]'

git pull

Recommended Alternative: Switch to SSH Protocol#

If the HTTPS proxy configuration is complex or unstable, the SSH protocol is a simpler and more reliable solution. SSH connections do not rely on HTTP/HTTPS proxies, thereby avoiding SSL interception and certificate trust issues.

Generate SSH Key Pair:
```
ssh-keygen -t ed25519 -C "user_email@example.com"
```
Accept the default path and leave the passphrase empty (for passwordless access).
Configure Public Key on the Code Hosting Platform:
- Copy the public key content: cat ~/.ssh/id_ed25519.pub.
- Log in to the target code hosting platform (e.g., GitLab, GitHub) and add this public key in the user settings.
Test SSH Connection:
```
ssh -T git@your-repo-domain.com
```
The first connection will trigger a host fingerprint verification prompt. Be sure to verify the fingerprint (e.g., consult the administrator for the official fingerprint) and, if correct, type yes and press enter. Upon success, a welcome message will be displayed.
Modify the local repository remote URL:

Navigate to the local repository directory:
```
git remote set-url origin git@your-repo-domain.com:your_group/your_repo.git
```
Execute git pull:
```
git pull
```
At this point, Git will pull the code via the SSH protocol, bypassing HTTPS proxy and certificate trust issues.

This article is synchronized and updated to xLog by Mix Space. The original link is https://blog.kanes.top/posts/default/97655532543870