How to fix unknown certificate issuer in Terraform

TerraformINTERMEDIATEHIGH

The "unknown certificate issuer" error occurs when Terraform cannot verify the SSL/TLS certificate of a remote endpoint because the certificate was signed by an untrusted or unrecognized Certificate Authority. This commonly happens with self-signed certificates, corporate proxies, or custom registries.

What this error means

When Terraform connects to remote services (like Terraform Registry, provider endpoints, or backends), it validates the SSL/TLS certificates to ensure secure communication. The "unknown certificate issuer" error means that the certificate presented by the server was signed by a Certificate Authority (CA) that your system does not trust. This can occur in several scenarios: - The server uses a self-signed certificate (signed by itself, not a trusted CA) - A corporate proxy or firewall performs SSL inspection and re-signs certificates - The certificate is signed by a private/internal CA not installed on your system - Your system's certificate store is out of date or corrupted Unlike expired certificate errors, this issue is specifically about certificate validation, not time-based validity.

How to fix "unknown certificate issuer"

1Identify the target server causing the error

First, identify which server certificate cannot be verified. The error message usually includes the hostname or endpoint. For example:

bash

Error: Failed to download module: unknown certificate issuer
Module source: registry.terraform.io/hashicorp/aws/latest

Or for a backend:

bash

Error: backend initialization required
Error: TLS verification failed: unknown certificate issuer

Note the hostname or URL that is failing.

2Download the server's CA certificate

Use openssl to fetch the certificate chain from the server:

bash

# Replace example.com with your server hostname
openssl s_client -connect example.com:443 -showcerts < /dev/null 2>/dev/null | openssl x509 -outform PEM > ca-cert.pem

# For private registries on non-standard ports
openssl s_client -connect registry.internal:8443 -showcerts < /dev/null 2>/dev/null | openssl x509 -outform PEM > ca-cert.pem

This creates a ca-cert.pem file with the server's certificate.

3Add certificate to system trust store (Linux)

On Linux, copy the certificate to the system CA directory and update the trust database:

bash

# Debian/Ubuntu
sudo cp ca-cert.pem /usr/local/share/ca-certificates/ca-cert.crt
sudo update-ca-certificates

# RHEL/CentOS/Fedora
sudo cp ca-cert.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

# Alpine
sudo cp ca-cert.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates

Verify with:

bash

ls /etc/ssl/certs/ | grep -i ca-cert

4Add certificate to system trust store (macOS)

On macOS, use the Keychain to add the certificate:

bash

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

# Or add to user keychain (no sudo needed)
security add-trusted-cert ca-cert.pem

Verify:

bash

security find-certificate -c ca-cert /Library/Keychains/System.keychain

5Add certificate to system trust store (Windows)

On Windows, import the certificate using PowerShell or Certificate Manager:

powershell

# PowerShell (run as Administrator)
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2 "ca-cert.pem"
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store "Root", "LocalMachine"
$store.Open("ReadWrite")
$store.Add($cert)
$store.Close()

Or use Certificate Manager:
1. Press Win+R, type certmgr.msc
2. Navigate to "Trusted Root Certification Authorities"
3. Right-click, select "Import..."
4. Browse and select ca-cert.pem

6Set SSL_CERT_FILE environment variable (alternative method)

If adding to system store is not possible, set the environment variable to use a custom certificate:

bash

# Linux/macOS
export SSL_CERT_FILE=/path/to/ca-cert.pem
terraform init

# Windows PowerShell
$env:SSL_CERT_FILE = "C:\path\to\ca-cert.pem"
terraform init

# Make persistent (Linux/macOS) - add to ~/.bashrc or ~/.zshrc
echo 'export SSL_CERT_FILE=/path/to/ca-cert.pem' >> ~/.bashrc
source ~/.bashrc

This tells Terraform and other Go-based tools to trust the specified certificate file.

7Handle corporate proxy SSL inspection

If behind a corporate proxy that re-signs certificates:

1. Obtain your organization's root CA certificate
2. Use one of the methods above to add it to your trust store
3. For Go applications (Terraform is built in Go), you can also:

bash

export SSL_CERT_FILE=/path/to/corporate-ca-bundle.pem

The root CA bundle should contain all certificates in the chain, from leaf to root.

Alternatively, create a combined certificate file:

bash

# Concatenate all CA certs
cat corporate-root-ca.pem > ca-bundle.pem
cat intermediate-ca.pem >> ca-bundle.pem

export SSL_CERT_FILE=/path/to/ca-bundle.pem

8Test certificate verification

Verify that certificate verification now works:

bash

# Test with curl
curl -v https://your-registry.example.com

# Test with openssl
openssl s_client -connect your-registry.example.com:443

# Then retry Terraform
terraform init

Both should complete without certificate verification errors.

How to fix unknown certificate issuer in Terraform

What this error means

Typical symptoms

Common causes

How to fix "unknown certificate issuer"

Advanced notes

Related errors

Official resources & further reading