How to fix unknown certificate issuer in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 129 views

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.

Quick fix

Fixes unknown certificate issuer

Error: Failed to download module: unknown certificate issuer
Module source: registry.terraform.io/hashicorp/aws/latest
  1. Identify the target server causing the error
  2. Download the server's CA certificate
  3. Add certificate to system trust store (Linux)
  4. Add certificate to system trust store (macOS)
terraform — error
Error: Failed to download module: unknown certificate issuer
Module source: registry.terraform.io/hashicorp/aws/latest
unknown certificate issuer

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.

Typical symptoms

  • Terraform init, plan, or apply fails with "unknown certificate issuer" message
  • Error specifically mentions "certificate verify failed" or "x509" errors
  • Private module registries or backends cannot be accessed
  • Error occurs when accessing registry.terraform.io or private registries
  • Behind corporate proxy: all remote operations fail with certificate errors
  • Other tools (curl, wget) may work but Terraform fails
  • Error persists even after retrying the command

Common causes

  1. Self-signed certificate on target server not added to system trust store
  2. Certificate signed by private/internal CA not in system certificate bundle
  3. Corporate proxy or firewall performing SSL inspection and re-signing certificates
  4. Outdated or missing CA certificates on the system
  5. Custom or non-standard TLS configuration on the target server
  6. Using IP address instead of hostname (certificate mismatch)
  7. Certificate is valid but CA is simply not trusted by the system

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.

Advanced notes

Security Note: Only add certificates to your trust store if you fully trust their origin. Adding untrusted certificates bypasses security protections.

Docker/Kubernetes: In containerized environments, ensure the CA certificate is copied into the image:

dockerfile
COPY ca-cert.pem /usr/local/share/ca-certificates/
RUN update-ca-certificates

Terraform Cloud/Enterprise: If using private Terraform Enterprise installations with self-signed certificates, Terraform Cloud agents automatically handle this. For self-managed agents, add the CA certificate to the host system.

GitHub Actions / CI/CD: In CI/CD pipelines, add the certificate during the setup step.

Provider-specific options: Some providers support insecure mode (not recommended for production):

hcl
provider "http" {
  insecure = true  # Disables certificate verification
}

Debugging: Enable verbose logging to see certificate chain details:

bash
TF_LOG=DEBUG terraform init

WSL2 / Virtual Machines: If running in WSL2 or VirtualBox, ensure the VM system clock is synchronized. Certificate validation fails if the system time is significantly off.

Frequently asked questions

What does "unknown certificate issuer" mean?
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 do I fix "unknown certificate issuer"?
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 causes "unknown certificate issuer"?
Self-signed certificate on target server not added to system trust store Certificate signed by private/internal CA not in system certificate bundle Corporate proxy or firewall performing SSL inspection and re-signing certificates
Is the "unknown certificate issuer" 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