Terraform: Failed to install provider, could not query provider registry

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Community providers need their real namespace
required_providers {
  gitlab = { source = "gitlabhq/gitlab", version = "~> 17.0" }   # not hashicorp/gitlab
}

# Behind a proxy or firewall
export HTTPS_PROXY=http://proxy:3128
curl -sI https://registry.terraform.io/.well-known/terraform.json

# Air gapped: mirror the providers once, then install offline
terraform providers mirror ./tf-mirror
terraform init -plugin-dir=./tf-mirror

# CI cache poisoned by a partial download
rm -rf .terraform && terraform init -upgrade

How to diagnose Terraform errors

Terraform errors are mostly state errors. A stuck lock, a resource that exists in the cloud but not in state, or a value that cannot be known until apply time all trace back to how Terraform models the world. The for_each-on-unknown-values error is the most common conceptual stumble: Terraform must know the keys of a map at plan time, even if the values are unknown.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. For a stuck lock, find out who holds it before forcing anything. terraform force-unlock <id> is safe only when you are certain no apply is running.
2. Use terraform state list and terraform state show <addr> to see what Terraform believes exists, and terraform import to adopt resources created outside it.
3. Set TF_LOG=DEBUG and TF_LOG_PATH=tf.log for provider-level detail on authentication and API errors.
4. For for_each errors, restructure so keys come from static values or from variables, not from attributes of resources that do not yet exist. Use -target for a staged apply as a last resort.
5. Run terraform plan -refresh-only to see drift explicitly before applying anything unexpected.

Tools worth reaching for

• terraform state list/show
• TF_LOG=DEBUG
• terraform plan -refresh-only
• terraform graph
• tflint / checkov

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 developer.hashicorp.com

Related Terraform errors

• OpenTofu: state is encrypted but no key provider is configuredOpenTofu can encrypt state and plan files at rest. Once a state has been written encrypted…
• Terraform: An argument named "x" is not expected hereThe configuration uses an argument the provider schema does not have. Usually the provider is…
• Terraform: Cannot import resource - not foundThe resource ID provided to terraform import does not match any existing resource in the…
• Terraform: Cycle (resources depend on each other)Terraform builds a dependency graph from references and cannot order a cycle. Two resources…
• Terraform: Cycle dependency detectedCircular dependency in resource definitions, resources depend on each other in a loop.
• Terraform: for_each value depends on resource attributes that cannot be determinedA for_each or count expression depends on a value that is not known until apply time…
• Terraform: Inconsistent dependency lock fileThe provider versions or platform hashes recorded in .terraform.lock.hcl do not cover what…
• Terraform: Instance cannot be destroyed (prevent_destroy)The resource carries a lifecycle block with prevent_destroy set, and the plan would destroy…

See all 18 Terraform errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.