TerraformPilot

DevOps

Fix Terraform Error: Provider Registry Not Reachable

Fix terraform registry not reachable errors behind corporate firewalls, VPNs, and air-gapped environments. Covers proxy config, provider mirrors

LLuca Berton1 min read

Quick Answer

# 
# Test connectivity
curl -sI https://registry.terraform.io/.well-known/terraform.json
 
# If behind a proxy
export HTTPS_PROXY=http://proxy.corp.com:8080
terraform init

The Error

# 
Error: Failed to query available provider packages
 
Could not retrieve the list of available versions for provider
hashicorp/aws: could not connect to registry.terraform.io:
  Failed to request discovery document: Get
  "https://registry.terraform.io/.well-known/terraform.json":
  dial tcp: lookup registry.terraform.io: no such host

Or:

Error: Failed to install provider
 
Error while installing hashicorp/aws v5.0.0: could not query
provider registry for registry.terraform.io/hashicorp/aws:
the request failed after 2 attempts

What Causes This

#
  1. Corporate firewall blocks registry.terraform.io or releases.hashicorp.com
  2. VPN routing doesn't route to HashiCorp endpoints
  3. DNS failure — can't resolve registry.terraform.io
  4. TLS interception — corporate proxy breaks SSL certificates
  5. Air-gapped environment — no internet at all

Solution 1: Configure Proxy

# 
# Set proxy for the current session
export HTTPS_PROXY=http://proxy.corp.com:8080
export HTTP_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.corp.com
 
terraform init

For CI/CD, set these in pipeline variables.

Solution 2: Whitelist Required Domains

#

Ask your network team to allow:

DomainPurpose
registry.terraform.ioProvider/module registry
releases.hashicorp.comProvider binary downloads
checkpoint-api.hashicorp.comVersion checking (optional)

All on port 443 (HTTPS).

Solution 3: Provider Filesystem Mirror

#

Download providers on a machine with internet, copy to the restricted machine:

# On a machine WITH internet access
mkdir -p /tmp/tf-mirror
cd /your/terraform/project
 
terraform providers mirror /tmp/tf-mirror
- Mirroring hashicorp/aws...
  - Selected v5.80.0 for linux_amd64
- Mirroring hashicorp/random...
  - Selected v3.6.0 for linux_amd64

Copy the mirror directory to the restricted machine, then configure:

# ~/.terraformrc (or terraform.rc on Windows)
provider_installation {
  filesystem_mirror {
    path    = "/opt/terraform/providers"
    include = ["registry.terraform.io/*/*"]
  }
  direct {
    exclude = ["registry.terraform.io/*/*"]
  }
}
terraform init
# Downloads from local filesystem instead of internet

Solution 4: Network Mirror (Private Registry)

#

Run a mirror server on your network:

# ~/.terraformrc
provider_installation {
  network_mirror {
    url = "https://terraform-mirror.internal.corp.com/providers/"
  }
}

Tools like Artifactory, Nexus, or the terraform-provider-mirror project can serve as network mirrors.

Solution 5: Bundle Providers in Version Control

#

For small projects, commit the .terraform.lock.hcl and cache providers in CI:

# GitLab CI
cache:
  key: terraform-providers-${CI_COMMIT_REF_SLUG}
  paths:
    - .terraform/providers/
 
init:
  script:
    - terraform init -plugin-dir=.terraform/providers/

Solution 6: TLS Certificate Issues

#

If your corporate proxy intercepts TLS:

# Add corporate CA certificate
export SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem
 
# Or skip verification (NOT recommended for production)
export TF_SKIP_PROVIDER_VERIFY=true

Debugging Connectivity

# 
# DNS resolution
nslookup registry.terraform.io
dig registry.terraform.io
 
# HTTPS connectivity
curl -v https://registry.terraform.io/.well-known/terraform.json
 
# Check if proxy is intercepting
openssl s_client -connect registry.terraform.io:443 -showcerts
 
# Terraform debug logs
export TF_LOG=TRACE
terraform init 2>&1 | grep -i "registry\|proxy\|tls\|connect"

Hands-On Courses

#

Conclusion

#

Registry not reachable means Terraform can't reach registry.terraform.io. Set HTTPS_PROXY for corporate proxies, whitelist the required domains, or use a filesystem mirror for air-gapped environments. For CI/CD, cache providers and use -plugin-dir to avoid downloading on every run.

#Terraform#Troubleshooting#DevOps#Error Fix#Infrastructure as Code

Share this article

Related articles