How to fix fatal: unable to access: SSL certificate subject name does not match target host in Git

GitINTERMEDIATEMEDIUM

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.

What this error means

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

How to fix "fatal: unable to access: SSL certificate subject name does not match target host"

1Verify the certificate issuer to confirm SSL inspection

First, check if your connection is being intercepted by a corporate proxy. The certificate issuer will reveal if this is the case:

bash

# 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 CA

You can also check via curl with verbose output:

bash

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.

2Obtain and 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:

bash

# 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.pem

3Configure Git to trust the corporate CA (recommended)

Once you have the corporate CA certificate, configure Git to use it:

Option A: Add to Git's certificate bundle

bash

# 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:

bash

sudo cp corporate-ca.pem /usr/local/share/ca-certificates/corporate-ca.crt
sudo update-ca-certificates

On RHEL/CentOS/Fedora:

bash

sudo cp corporate-ca.pem /etc/pki/ca-trust/source/anchors/corporate-ca.crt
sudo update-ca-trust

On macOS:

bash

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain corporate-ca.pem

After adding to the system store, Git should automatically trust it.

4Configure Git to use Windows certificate store (Windows users)

On Windows, the corporate CA is often already installed in the Windows certificate store by IT policies. Configure Git to use it:

bash

# Use Windows Secure Channel for SSL
git config --global http.sslBackend schannel

This 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:

bash

git config --global http.sslBackend
# Should output: schannel

If you need to revert to OpenSSL:

bash

git config --global http.sslBackend openssl

5Use SSH instead of HTTPS

If 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)

bash

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

bash

# 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 -v

Step 4: Test the connection

bash

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:

bash

# 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 git

6Check DNS resolution and network configuration

Verify that DNS is resolving correctly and your connection is going to the expected server:

bash

# 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.proxy

If DNS returns unexpected results or you're being routed through a proxy you didn't configure:

bash

# Check /etc/resolv.conf for unexpected DNS servers
cat /etc/resolv.conf

# Try using a specific DNS server
nslookup github.com 8.8.8.8

If a proxy is configured that shouldn't be:

bash

# Remove proxy configuration
git config --global --unset http.proxy
git config --global --unset https.proxy
unset http_proxy
unset https_proxy

7Disable SSL verification temporarily (not recommended)

Warning: 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.

bash

# 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 false

Re-enable immediately after testing:

bash

git config --global http.sslVerify true
git config --global --unset http.https://github.com/.sslVerify

Disabling 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.

Advanced notes

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:

bash

# Check which SSL library Git uses
ldd $(which git) | grep -i ssl
# or
git --version --build-options | grep -i ssl

If you're using GnuTLS and having issues, you may need to add certificates to the GnuTLS trust store:

bash

# GnuTLS certificate location (varies by distribution)
/etc/ssl/certs/ca-certificates.crt

CI/CD pipeline considerations:
In CI/CD environments, you may need to inject the corporate CA certificate:

yaml

# 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

# Dockerfile example
COPY corporate-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

Debugging SSL handshake failures:

bash

# 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:

bash

# 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"

How to fix fatal: unable to access: SSL certificate subject name does not match target host in Git

What this error means

Typical symptoms

Common causes

How to fix "fatal: unable to access: SSL certificate subject name does not match target host"

Advanced notes

Related errors

Official resources & further reading