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.
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.
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.
Try to manually access the registry using curl:
curl https://registry.terraform.io/.well-known/terraform.jsonIf this works but Terraform still fails, it's a Terraform-specific issue, not a network problem.
Test DNS resolution for registry.terraform.io:
nslookup registry.terraform.io
# or
dig registry.terraform.ioYou should see a valid IP address returned. If not, DNS is the problem.
If DNS resolution is failing, try using a public DNS server:
# Temporarily use Google's DNS
sudo bash -c 'echo nameserver 8.8.8.8 > /etc/resolv.conf'
# Try terraform init again
terraform initFor permanent changes, update your system's DNS configuration (varies by OS).
If you're behind a corporate proxy, configure Terraform to use it:
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 initAlternatively, create ~/.terraformrc with proxy settings.
If you're running Terraform older than 1.0.1, upgrade to fix DNS resolution issues:
terraform version # Check current version
# Download and install latest: https://www.terraform.io/downloadsVersions prior to 1.0.1 had a cross-platform DNS client issue on macOS/Linux that could cause registry connection failures.
If your environment doesn't have internet access, configure Terraform to use a local mirror:
Create ~/.terraformrc:
provider_installation {
filesystem_mirror {
path = "./terraform/providers"
include = ["hashicorp/*"]
}
direct {
exclude = ["hashicorp/*"]
}
}Then copy pre-downloaded providers to the filesystem_mirror directory.
After applying any fixes above, try again:
terraform initIf successful, you should see messages like 'Terraform has been successfully initialized!'
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:
export TF_LOG=DEBUG # Enable debug logging to see connection details
export HTTP_CLIENT_READ_TIMEOUT=5m2. 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.
Error: Error installing helm release: cannot re-use a name that is still in use
How to fix "release name in use" error in Terraform with Helm
Error: Error creating GKE Cluster: BadRequest
BadRequest error creating GKE cluster in Terraform
Error: External program failed to produce valid JSON
External program failed to produce valid JSON
Error: Unsupported argument in child module call
How to fix "Unsupported argument in child module call" in Terraform
Error: network is unreachable
How to fix "network is unreachable" in Terraform