This error occurs when Git cannot verify the SSL certificate because the certificate's subject name (CN or SAN) does not match the hostname you are connecting to. This is most commonly caused by corporate SSL inspection proxies that intercept HTTPS traffic and re-sign it with their own certificates.
The "SSL certificate subject name does not match target host" error occurs when Git's SSL/TLS verification fails due to a hostname mismatch. Every SSL certificate contains a subject name (Common Name or Subject Alternative Names) that specifies which domains the certificate is valid for. When Git connects to a remote server, it checks if the certificate's subject matches the hostname in the URL. This error is most commonly seen in corporate environments where a Cloud Access Security Broker (CASB) or SSL inspection proxy intercepts HTTPS traffic. These systems perform a man-in-the-middle inspection by: 1. Intercepting the connection to the remote Git server (GitHub, GitLab, etc.) 2. Decrypting the traffic for security scanning 3. Re-encrypting the traffic with a certificate signed by the corporate Certificate Authority The problem arises when the corporate proxy's certificate does not properly include the correct hostname, or when your system does not trust the corporate CA that signed this replacement certificate. Other scenarios that cause this error include: - Accessing a Git server through a load balancer or reverse proxy with misconfigured certificates - DNS resolution returning a different IP than expected, leading to a certificate for a different domain - Using an IP address instead of a hostname when the certificate only contains domain names - Self-hosted Git servers with improperly configured SSL certificates
First, check if your connection is being intercepted by a corporate proxy. The certificate issuer will reveal if this is the case:
# Check the certificate issuer for GitHub
openssl s_client -connect github.com:443 -servername github.com </dev/null 2>/dev/null | openssl x509 -noout -issuer
# Expected output for direct connection:
# issuer=C = US, O = DigiCert Inc, CN = DigiCert High Assurance TLS RSA SHA256 2020 CA1
# If you see your company name in the issuer, SSL inspection is active
# Example corporate issuer:
# issuer=C = US, O = YourCompany, CN = YourCompany Security Proxy CAYou can also check via curl with verbose output:
curl -v https://github.com 2>&1 | grep -i "issuer\|subject"If the issuer is your company's CA, proceed to install the corporate CA certificate.
Contact your IT department to get the corporate root CA certificate, or export it from your browser:
Export from browser (Chrome):
1. Navigate to https://github.com (or your Git host)
2. Click the lock icon in the address bar
3. Click "Connection is secure" > "Certificate is valid"
4. Go to the "Certification Path" tab
5. Select the root certificate (top of the chain)
6. Click "View Certificate" > "Details" > "Copy to File"
7. Export as Base-64 encoded X.509 (.CER)
Export from browser (Firefox):
1. Navigate to https://github.com
2. Click the lock icon > "Connection secure" > "More Information"
3. Click "View Certificate"
4. Click on the root certificate in the chain
5. Scroll down and click "PEM (cert)" to download
Extract certificate via command line:
# Extract the root CA certificate from the connection
openssl s_client -showcerts -connect github.com:443 -servername github.com </dev/null 2>/dev/null | \
sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' > corporate-ca.pemOnce you have the corporate CA certificate, configure Git to use it:
Option A: Add to Git's certificate bundle
# Configure Git to use a specific CA certificate file
git config --global http.sslCAInfo /path/to/corporate-ca.pem
# Or specify the certificate directory
git config --global http.sslCAPath /path/to/certs/directory/Option B: Add to system certificate store
On Ubuntu/Debian:
sudo cp corporate-ca.pem /usr/local/share/ca-certificates/corporate-ca.crt
sudo update-ca-certificatesOn RHEL/CentOS/Fedora:
sudo cp corporate-ca.pem /etc/pki/ca-trust/source/anchors/corporate-ca.crt
sudo update-ca-trustOn macOS:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain corporate-ca.pemAfter adding to the system store, Git should automatically trust it.
On Windows, the corporate CA is often already installed in the Windows certificate store by IT policies. Configure Git to use it:
# Use Windows Secure Channel for SSL
git config --global http.sslBackend schannelThis tells Git to use the Windows certificate store instead of its bundled OpenSSL certificates. Since corporate CA certificates are typically deployed via Group Policy to the Windows store, this often resolves the issue immediately.
Verify the setting:
git config --global http.sslBackend
# Should output: schannelIf you need to revert to OpenSSL:
git config --global http.sslBackend opensslIf SSL inspection continues to cause issues, switching to SSH for Git operations bypasses HTTPS entirely. Many corporate networks allow SSH connections:
Step 1: Generate an SSH key (if you don't have one)
ssh-keygen -t ed25519 -C "[email protected]"Step 2: Add the public key to your Git hosting service
- GitHub: Settings > SSH and GPG keys > New SSH key
- GitLab: Preferences > SSH Keys
- Bitbucket: Personal settings > SSH keys
Step 3: Update your remote URL to use SSH
# View current remote
git remote -v
# Change from HTTPS to SSH
git remote set-url origin [email protected]:username/repository.git
# Verify the change
git remote -vStep 4: Test the connection
ssh -T [email protected]
# Expected: "Hi username! You've successfully authenticated..."Note: Some corporate firewalls block port 22 (SSH). GitHub and GitLab offer SSH over port 443 as an alternative:
# Test SSH over HTTPS port for GitHub
ssh -T -p 443 [email protected]
# Configure SSH to always use port 443 for GitHub
# Add to ~/.ssh/config:
Host github.com
Hostname ssh.github.com
Port 443
User gitVerify that DNS is resolving correctly and your connection is going to the expected server:
# Check DNS resolution
nslookup github.com
dig github.com
# Verify you can reach the server
ping github.com
# Check if there's a proxy configured
echo $http_proxy
echo $https_proxy
git config --global --get http.proxyIf DNS returns unexpected results or you're being routed through a proxy you didn't configure:
# Check /etc/resolv.conf for unexpected DNS servers
cat /etc/resolv.conf
# Try using a specific DNS server
nslookup github.com 8.8.8.8If a proxy is configured that shouldn't be:
# Remove proxy configuration
git config --global --unset http.proxy
git config --global --unset https.proxy
unset http_proxy
unset https_proxyWarning: Disabling SSL verification removes a critical security protection. Only use this for temporary debugging or in isolated development environments. Never use this for production or sensitive repositories.
# Disable for a single command only
GIT_SSL_NO_VERIFY=true git clone https://github.com/user/repo.git
# Disable for a specific repository
git config http.sslVerify false
# Disable for a specific domain only (slightly better)
git config --global http.https://github.com/.sslVerify false
# Disable globally (STRONGLY NOT RECOMMENDED)
git config --global http.sslVerify falseRe-enable immediately after testing:
git config --global http.sslVerify true
git config --global --unset http.https://github.com/.sslVerifyDisabling SSL verification makes your Git traffic vulnerable to man-in-the-middle attacks. Anyone on your network path could intercept credentials and repository content without detection. Only use this to confirm the issue is SSL-related, then implement a proper fix using the corporate CA certificate.
Understanding SSL inspection and its security implications:
Corporate SSL inspection (also called SSL/TLS interception, HTTPS inspection, or MITM proxying) is a security practice where network security appliances decrypt and inspect encrypted traffic. While this provides security benefits like malware detection and data loss prevention, it has important implications:
1. Your Git credentials pass through the proxy in plaintext (after decryption)
2. Repository contents are visible to the security appliance
3. The security of your connection depends on the proxy's certificate handling
This is why properly configuring the corporate CA is important - it ensures you're still protected against attacks from outside your corporate network.
GnuTLS vs OpenSSL backend:
Some Linux distributions compile Git with GnuTLS instead of OpenSSL as the SSL backend. This can cause issues with corporate certificates because GnuTLS handles certificates differently:
# Check which SSL library Git uses
ldd $(which git) | grep -i ssl
# or
git --version --build-options | grep -i sslIf you're using GnuTLS and having issues, you may need to add certificates to the GnuTLS trust store:
# GnuTLS certificate location (varies by distribution)
/etc/ssl/certs/ca-certificates.crtCI/CD pipeline considerations:
In CI/CD environments, you may need to inject the corporate CA certificate:
# GitHub Actions example
jobs:
build:
steps:
- name: Install corporate CA
run: |
echo "$CORPORATE_CA_CERT" | sudo tee /usr/local/share/ca-certificates/corporate.crt
sudo update-ca-certificates
env:
CORPORATE_CA_CERT: ${{ secrets.CORPORATE_CA_CERT }}# Dockerfile example
COPY corporate-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificatesDebugging SSL handshake failures:
# Verbose SSL debugging
GIT_CURL_VERBOSE=1 GIT_TRACE=1 git fetch
# Test SSL handshake directly
openssl s_client -connect github.com:443 -servername github.com -debug
# Check certificate chain
openssl s_client -showcerts -connect github.com:443 -servername github.com </dev/null 2>/dev/null | \
openssl storeutl -noout -text -certs /dev/stdin
# Verify certificate matches hostname
openssl s_client -connect github.com:443 -servername github.com </dev/null 2>/dev/null | \
openssl x509 -noout -text | grep -A1 "Subject Alternative Name"Working with self-hosted Git servers:
If you manage a self-hosted Git server (GitLab, Gitea, etc.) and users are seeing this error, ensure your SSL certificate includes all necessary Subject Alternative Names:
# Generate certificate with SANs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout server.key -out server.crt \
-subj "/CN=git.example.com" \
-addext "subjectAltName=DNS:git.example.com,DNS:gitlab.example.com,IP:10.0.0.100"kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server
fatal: unable to access: Proxy auto-configuration failed
How to fix 'Proxy auto-configuration failed' in Git
fatal: unable to access: Authentication failed (proxy requires basic auth)
How to fix 'Authentication failed (proxy requires basic auth)' in Git
fatal: unable to access: no_proxy configuration not working
How to fix 'no_proxy configuration not working' in Git
fatal: unable to read tree object in treeless clone
How to fix 'unable to read tree object in treeless clone' in Git