How to fix x509 certificate error in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 123 views

The x509 certificate error occurs when Terraform cannot verify the SSL/TLS certificate of a server. This typically happens with self-signed certificates, custom CAs, or corporate proxies. Resolve by adding the certificate to your system's trust store or configuring Terraform to recognize the CA.

Quick fix

Fixes x509 certificate error

TF_LOG=DEBUG terraform init
  1. Identify the certificate issuer
  2. Export the CA certificate
  3. Add certificate to system trust store (Linux)
  4. Add certificate to system trust store (macOS)
terraform — error
TF_LOG=DEBUG terraform init
x509 certificate error

What this error means

An x509 certificate error indicates a failure in the SSL/TLS certificate verification process. X.509 is the standard format for digital certificates. Terraform verifies the certificate chain of any server it connects to—whether that's Terraform Cloud, a backend state server, or an API endpoint. When Terraform encounters a certificate it cannot verify, it refuses the connection to protect against man-in-the-middle attacks. The error means either: (1) the certificate was signed by an untrusted Certificate Authority (CA) that is not in your system's trust store, (2) the certificate chain is incomplete, (3) the certificate is self-signed, (4) the certificate has expired, or (5) a corporate proxy is intercepting the connection with its own certificate.

Typical symptoms

  • Terraform init fails with "x509: certificate signed by unknown authority"
  • Terraform login command fails with certificate verification error
  • terraform plan or apply fails when connecting to state backend
  • Docker or Kubernetes provider errors referencing x509 certificates
  • Error occurs only behind corporate firewall or proxy
  • Runs succeed locally but fail in CI/CD environment
  • Error message includes "certificate is not valid for any names"

Common causes

  1. Certificate is self-signed and not in system trust store
  2. Certificate signed by custom or internal Certificate Authority not recognized by system
  3. Corporate proxy or firewall intercepting SSL connections
  4. Incomplete certificate chain (missing intermediate certificates)
  5. Terraform Enterprise using self-signed or custom-signed TLS certificate
  6. System clock is incorrect, causing valid certificates to appear expired
  7. Zscaler or similar security tool interfering with certificate validation
  8. Certificate has been revoked but system cannot check revocation status

How to fix "x509 certificate error"

1Identify the certificate issuer

First, determine which certificate is failing verification. Run Terraform with verbose logging to see the hostname:

bash
TF_LOG=DEBUG terraform init

Look for the server hostname in the error message. Then examine its certificate:

bash
# For a web server
openssl s_client -connect example.com:443 -servername example.com < /dev/null | openssl x509 -text -noout

# For Terraform Enterprise
openssl s_client -connect tfe.company.com:443 < /dev/null | openssl x509 -text -noout

Note the "Issuer" field in the certificate output. If it says your organization or contains "CN=.*Internal", it's a custom or self-signed certificate.

2Export the CA certificate

If the certificate was issued by a custom CA, you need to obtain the root CA certificate. Common ways to do this:

From a server with the certificate:

bash
# Export the certificate chain
openssl s_client -connect example.com:443 -showcerts < /dev/null |   sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ca-bundle.crt

From your organization's certificate store:
Ask your IT department for the root CA certificate or intermediate CA certificate in PEM format.

From Terraform Enterprise admin UI:
If using Terraform Enterprise, you can often export the certificate from the Replicated admin console on port 8800.

3Add certificate to system trust store (Linux)

Copy the CA certificate to the system's CA directory and update the trust store:

bash
# Copy the certificate
sudo cp ca-bundle.crt /usr/local/share/ca-certificates/custom-ca.crt

# Ensure proper permissions
sudo chmod 644 /usr/local/share/ca-certificates/custom-ca.crt

# Update the trust store
sudo update-ca-certificates

Verify the update succeeded:

bash
ls -la /etc/ssl/certs/ | grep custom-ca
4Add certificate to system trust store (macOS)

On macOS, use the security command to add the certificate to Keychain:

bash
# Convert PEM to DER if needed (some tools require DER)
openssl x509 -inform PEM -in ca-bundle.crt -outform DER -out ca-bundle.cer

# Add to System Keychain
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca-bundle.crt

# Or for current user only
security add-trusted-cert -d -r trustRoot ca-bundle.crt

Note: If you see "The certificate is not trusted" dialog, click "Always Trust" to add it to the keychain.

5Add certificate to system trust store (Windows)

On Windows, use the certutil command or Certificate Manager:

Via Command Prompt (admin):

batch
certutil -addstore -f "ROOT" ca-bundle.crt

Via Certificate Manager GUI:
1. Press Win+R and type mmc
2. Click File → Add/Remove Snap-in
3. Select "Certificates" and click Add
4. Choose "Computer Account" (for system-wide) or "My user account" (for current user)
5. Navigate to Certificates → Trusted Root Certification Authorities
6. Right-click and select "All Tasks" → "Import"
7. Browse to your CA certificate file and complete the import wizard

6Verify the certificate is trusted

After adding the certificate to the trust store, verify it works:

bash
# Test with OpenSSL
openssl verify -CAfile ca-bundle.crt -untrusted ca-bundle.crt ca-bundle.crt

# Or for a remote server
openssl s_client -connect example.com:443 -CAfile ca-bundle.crt -servername example.com

Then retry your Terraform command:

bash
terraform init
terraform plan

Advanced notes

Terraform Enterprise with Custom TLS:
If you run Terraform Enterprise with a custom TLS certificate, all workers and CLI clients must have the Terraform Enterprise CA in their trust store. This is configured on the Replicated admin console (port 8800) under Settings → SSL/TLS Configuration. Certificates must be PEM-encoded.

Corporate Proxy Interception:
Some corporate security tools (like Zscaler) use a technique called "SSL/TLS inspection" where they intercept connections and present their own certificate signed by a corporate CA. If you get x509 errors only behind your corporate firewall, this is likely the cause. Ask your IT/security team for the corporate CA certificate bundle.

System Clock Issues:
If certificates appear invalid even though the chain is correct, verify your system clock is accurate. Use NTP to sync:

bash
# Linux
timedatectl set-ntp true
sudo ntpdate -s time.nist.gov

# macOS
sudo sntp -sS time.apple.com

Offline Mode / Air-Gapped Environments:
In offline Terraform Enterprise installations or air-gapped networks, you may need to manually download and configure CA certificates. Refer to the offline deployment guide in your Terraform Enterprise documentation.

Debugging Certificate Chains:
To see the full certificate chain that a server presents:

bash
openssl s_client -connect example.com:443 -showcerts -servername example.com

The output shows the end-entity certificate first, followed by intermediate certificates, ending with the root CA.

Frequently asked questions

What does "x509 certificate error" mean?
An x509 certificate error indicates a failure in the SSL/TLS certificate verification process. 509 is the standard format for digital certificates. Terraform verifies the certificate chain of any server it connects to—whether that's Terraform Cloud, a backend state server, or an API endpoint.
How do I fix "x509 certificate error"?
The x509 certificate error occurs when Terraform cannot verify the SSL/TLS certificate of a server. This typically happens with self-signed certificates, custom CAs, or corporate proxies. Resolve by adding the certificate to your system's trust store or configuring Terraform to recognize the CA.
What causes "x509 certificate error"?
Certificate is self-signed and not in system trust store Certificate signed by custom or internal Certificate Authority not recognized by system Corporate proxy or firewall intercepting SSL connections
Is the "x509 certificate error" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading