How to fix could not connect to registry.terraform.io in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 155 views

This error occurs when Terraform cannot establish a connection to registry.terraform.io to download provider packages during 'terraform init'. It typically results from network issues, DNS resolution problems, proxy misconfiguration, or firewall restrictions.

Quick fix

Fixes could not connect to registry.terraform.io

curl https://registry.terraform.io/.well-known/terraform.json
  1. Check HashiCorp status page
  2. Test basic network connectivity
  3. Check DNS resolution
  4. Configure DNS settings if needed
terraform — error
curl https://registry.terraform.io/.well-known/terraform.json
could not connect to registry.terraform.io

What this error means

When you run 'terraform init', Terraform needs to download provider plugins (like hashicorp/aws, hashicorp/google, etc.) from the Terraform Registry at registry.terraform.io. If the connection fails, you'll see an error message like 'Could not retrieve the list of available versions for provider: could not connect to registry.terraform.io: Failed to request discovery document'. This prevents Terraform from initializing your configuration and downloading the required providers.

Typical symptoms

  • terraform init fails with 'could not connect to registry.terraform.io' error
  • Error message mentions 'Failed to request discovery document'
  • Client.Timeout exceeded while awaiting headers
  • Registry service appears unreachable in error message
  • You can access other websites but not registry.terraform.io

Common causes

  1. Network connectivity issues or firewall blocking access to registry.terraform.io
  2. DNS resolution failures preventing lookup of registry.terraform.io IP address
  3. Corporate proxy misconfiguration or proxy not allowing HTTPS connections to the registry
  4. DNS resolver returning incorrect authority information causing Terraform to query wrong IP address
  5. TLS handshake timeout when connecting to the registry
  6. Terraform version older than 1.0.1 with cross-platform DNS client issues on macOS/Linux
  7. Intermittent connectivity issues with HashiCorp's CDN (Fastly)
  8. Registry service temporarily unavailable or experiencing outages

How to fix "could not connect to registry.terraform.io"

1Check HashiCorp status page

Visit https://status.hashicorp.com/ to verify that registry.terraform.io is operational. If there's a reported outage, wait until it's resolved before continuing.

2Test basic network connectivity

Try to manually access the registry using curl:

bash
curl https://registry.terraform.io/.well-known/terraform.json

If this works but Terraform still fails, it's a Terraform-specific issue, not a network problem.

3Check DNS resolution

Test DNS resolution for registry.terraform.io:

bash
nslookup registry.terraform.io
# or
dig registry.terraform.io

You should see a valid IP address returned. If not, DNS is the problem.

4Configure DNS settings if needed

If DNS resolution is failing, try using a public DNS server:

bash
# Temporarily use Google's DNS
sudo bash -c 'echo nameserver 8.8.8.8 > /etc/resolv.conf'

# Try terraform init again
terraform init

For permanent changes, update your system's DNS configuration (varies by OS).

5Check and configure proxy settings

If you're behind a corporate proxy, configure Terraform to use it:

bash
export HTTP_PROXY=http://proxy-server:port
export HTTPS_PROXY=http://proxy-server:port
# Optional: if proxy requires authentication
export HTTP_PROXY=http://username:password@proxy-server:port

terraform init

Alternatively, create ~/.terraformrc with proxy settings.

6Upgrade Terraform to the latest version

If you're running Terraform older than 1.0.1, upgrade to fix DNS resolution issues:

bash
terraform version  # Check current version

# Download and install latest: https://www.terraform.io/downloads

Versions prior to 1.0.1 had a cross-platform DNS client issue on macOS/Linux that could cause registry connection failures.

7Use a local mirror for offline/air-gapped environments

If your environment doesn't have internet access, configure Terraform to use a local mirror:

Create ~/.terraformrc:

hcl
provider_installation {
  filesystem_mirror {
    path    = "./terraform/providers"
    include = ["hashicorp/*"]
  }
  direct {
    exclude = ["hashicorp/*"]
  }
}

Then copy pre-downloaded providers to the filesystem_mirror directory.

8Retry terraform init

After applying any fixes above, try again:

bash
terraform init

If successful, you should see messages like 'Terraform has been successfully initialized!'

Advanced notes

Intermittent failures: Some users have reported intermittent connectivity issues to registry.terraform.io (roughly 3-5% of connection attempts failing). If you experience sporadic failures, you can:

1. Increase the Terraform timeout by setting environment variables:

bash
export TF_LOG=DEBUG  # Enable debug logging to see connection details
export HTTP_CLIENT_READ_TIMEOUT=5m

2. Create ~/.terraformrc with explicit timeout settings for the registry.

3. Implement retry logic in your CI/CD pipeline (retry terraform init up to 3 times before failing).

VPN/DNS Authority Information Issues: On systems that provide authority information in DNS responses (common in some enterprise networks), Terraform may query the wrong IP address for registry.terraform.io. If this happens, manually set DNS or use a public DNS server as a workaround.

Rootless Docker in CI: If running in Docker or containerized CI systems, ensure the container has proper DNS configuration and network access.

Private Registry: If using a private Terraform Module Registry instead of the public one, ensure your API token is set in ~/.terraformrc with proper credentials.

Frequently asked questions

What does "could not connect to registry.terraform.io" mean?
io. io: Failed to request discovery document'. This prevents Terraform from initializing your configuration and downloading the required providers.
How do I fix "could not connect to registry.terraform.io"?
This error occurs when Terraform cannot establish a connection to registry.terraform.io to download provider packages during 'terraform init'. It typically results from network issues, DNS resolution problems, proxy misconfiguration, or firewall restrictions.
What causes "could not connect to registry.terraform.io"?
Network connectivity issues or firewall blocking access to registry.terraform.io DNS resolution failures preventing lookup of registry.terraform.io IP address Corporate proxy misconfiguration or proxy not allowing HTTPS connections to the registry
Is the "could not connect to registry.terraform.io" 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