How to Fix Gemini CLI SSL/TLS Certificate Errors

SSL/TLS certificate errors are one of the most common issues developers encounter when using Gemini CLI in corporate environments. These errors occur when Node.js cannot verify the SSL certificate chain between your machine and Google's API servers.

Understanding SSL/TLS Errors

When Gemini CLI connects to Google's API, it establishes an encrypted HTTPS connection. Your system must verify that the server's SSL certificate is valid and issued by a trusted Certificate Authority (CA). When this verification fails, you see errors like:

• UNABLE_TO_VERIFY_LEAF_SIGNATURE
• SELF_SIGNED_CERT_IN_CHAIN
• CERT_HAS_EXPIRED
• DEPTH_ZERO_SELF_SIGNED_CERT
• unable to get local issuer certificate

Common Error Messages and Causes

UNABLE_TO_VERIFY_LEAF_SIGNATURE

This error indicates the certificate chain is incomplete or the root CA is not trusted:

Error: unable to verify the first certificate
    at TLSSocket.onConnectSecure
    code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'

Common causes:

• Corporate proxy performing SSL inspection
• Missing intermediate certificates
• Custom CA certificate not added to Node.js trust store

SELF_SIGNED_CERT_IN_CHAIN

Your network is intercepting HTTPS traffic with a self-signed certificate:

Error: self signed certificate in certificate chain
    code: 'SELF_SIGNED_CERT_IN_CHAIN'

Common causes:

• Corporate firewall or proxy SSL inspection
• Development environment with self-signed certificates
• Network security appliance (Zscaler, Palo Alto, etc.)

CERT_HAS_EXPIRED

The certificate has passed its validity period:

Error: certificate has expired
    code: 'CERT_HAS_EXPIRED'

Common causes:

• System clock is incorrect
• Cached certificate needs renewal
• Proxy certificate expired

Corporate Proxy and SSL Inspection

Many organizations use SSL inspection (also called SSL decryption or HTTPS inspection) to monitor encrypted traffic. This requires your tools to trust your organization's root CA certificate.

Step 1: Obtain Your Corporate CA Certificate

Contact your IT department to get the corporate root CA certificate. Common file formats:

• .pem (Privacy Enhanced Mail) - Base64 encoded
• .crt (Certificate) - Can be PEM or DER encoded
• .cer (Certificate) - Usually DER encoded

Step 2: Configure NODE_EXTRA_CA_CERTS

Node.js uses the NODE_EXTRA_CA_CERTS environment variable to load additional trusted certificates.

macOS/Linux:

# Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile)
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem"

# Apply changes
source ~/.zshrc  # or ~/.bashrc

Windows (PowerShell):

# Set for current session
$env:NODE_EXTRA_CA_CERTS="C:\path\to\corporate-ca.pem"

# Set permanently (run as Administrator)
[System.Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", "C:\path\to\corporate-ca.pem", "User")

Windows (Command Prompt):

setx NODE_EXTRA_CA_CERTS "C:\path\to\corporate-ca.pem"

Step 3: Configure Proxy Environment Variables

If your organization uses a proxy server:

macOS/Linux:

export HTTPS_PROXY="http://proxy.yourcompany.com:8080"
export HTTP_PROXY="http://proxy.yourcompany.com:8080"
export NO_PROXY="localhost,127.0.0.1,.yourcompany.com"

Windows (PowerShell):

$env:HTTPS_PROXY="http://proxy.yourcompany.com:8080"
$env:HTTP_PROXY="http://proxy.yourcompany.com:8080"
$env:NO_PROXY="localhost,127.0.0.1,.yourcompany.com"

Platform-Specific Certificate Locations

macOS

System certificates are stored in Keychain Access. To export your corporate CA:

1. Open Keychain Access
2. Select System or System Roots keychain
3. Find your corporate CA certificate
4. Right-click and select Export
5. Save as .pem format

Common certificate bundle location:

/etc/ssl/cert.pem

Windows

Windows stores certificates in the Certificate Manager:

1. Press Win + R, type certmgr.msc
2. Navigate to Trusted Root Certification Authorities > Certificates
3. Find and export your corporate CA certificate

To export via PowerShell:

Get-ChildItem -Path Cert:\LocalMachine\Root | Where-Object { $_.Subject -like "*YourCompany*" } | Export-Certificate -FilePath corporate-ca.cer

Linux

System certificates are typically located in:

• Ubuntu/Debian: /etc/ssl/certs/ and /usr/local/share/ca-certificates/
• RHEL/CentOS: /etc/pki/tls/certs/ and /etc/pki/ca-trust/source/anchors/
• Arch Linux: /etc/ca-certificates/trust-source/anchors/

To add a certificate on Ubuntu/Debian:

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

System Clock Synchronization

SSL certificates have validity periods. If your system clock is wrong, certificates may appear expired or not yet valid.

Check your system time:

# macOS/Linux
date

# Windows PowerShell
Get-Date

Synchronize time:

macOS:

sudo sntp -sS time.apple.com

Linux:

sudo timedatectl set-ntp true
# or
sudo ntpdate pool.ntp.org

Windows:

w32tm /resync

Debugging SSL Issues

Using OpenSSL to Diagnose

OpenSSL is invaluable for debugging certificate issues:

# View the certificate chain
openssl s_client -connect generativelanguage.googleapis.com:443 -showcerts

# Check through a proxy
openssl s_client -connect generativelanguage.googleapis.com:443 -proxy proxy.company.com:8080

# Verify certificate dates
openssl s_client -connect generativelanguage.googleapis.com:443 2>/dev/null | openssl x509 -noout -dates

Enable Node.js Debug Logging

# macOS/Linux
NODE_DEBUG=tls gemini "test"

# Windows PowerShell
$env:NODE_DEBUG="tls"; gemini "test"

Test Certificate Configuration

Create a simple test script to verify your certificate setup:

// test-ssl.js
const https = require('https');

https.get('https://generativelanguage.googleapis.com', (res) => {
  console.log('SSL connection successful');
  console.log('Status:', res.statusCode);
}).on('error', (e) => {
  console.error('SSL Error:', e.message);
  console.error('Code:', e.code);
});

Run with:

node test-ssl.js

Safe vs Unsafe Workarounds

Safe: Configure Trusted Certificates

Always prefer adding the correct CA certificates:

export NODE_EXTRA_CA_CERTS="/path/to/ca-bundle.pem"

Unsafe: Disabling SSL Verification (NOT Recommended)

Disabling SSL verification exposes you to man-in-the-middle attacks:

# DO NOT USE IN PRODUCTION - Security Risk
export NODE_TLS_REJECT_UNAUTHORIZED=0

This should only be used for temporary debugging in isolated development environments. Never use this in production or when handling sensitive data.

Creating a Combined CA Bundle

If you need to trust multiple certificates, combine them into a single PEM file:

# Combine certificates
cat system-ca-bundle.pem corporate-ca.pem > combined-ca-bundle.pem

# Use the combined bundle
export NODE_EXTRA_CA_CERTS="$HOME/.ssl/combined-ca-bundle.pem"

Troubleshooting Checklist

1. Verify the error message - Identify the specific SSL error code
2. Check system clock - Ensure your system time is accurate
3. Identify certificate source - Determine if it's a corporate proxy or missing CA
4. Obtain correct certificate - Get the CA certificate from your IT team
5. Configure NODE_EXTRA_CA_CERTS - Point to your CA bundle
6. Set proxy variables - Configure HTTPS_PROXY if needed
7. Test with openssl - Verify the certificate chain
8. Restart your terminal - Ensure environment variables are loaded

Next Steps

• Learn how to install Gemini CLI if you have not already
• Configure MCP integrations for enhanced functionality
• Explore Vertex AI Enterprise setup for organizational use