🚨 Terraform Error Guide: 'Failed to query available provider packages' on init

Exact Error Message

This fires during terraform init, before any plugin is downloaded. It is the headline error; the line underneath tells you why the registry query failed.

Error: Failed to query available provider packages

Could not retrieve the list of available versions for provider
hashicorp/aws: no available releases match the given constraints
>= 4.0.0, >= 5.20.0, < 5.0.0

Two other common variants point at the registry or the source address rather than the constraints:

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

Error: Failed to query available provider packages

Could not retrieve the list of available versions for provider
example-corp/widget: provider registry registry.terraform.io does not
have a provider named registry.terraform.io/example-corp/widget

What the Error Means

During init, Terraform contacts a provider registry (default registry.terraform.io) to enumerate every published version of each provider, then selects the newest version that satisfies all required_providers constraints across your root module and every child module. “Failed to query available provider packages” means that enumeration step failed. Either no published version satisfies the combined constraints, the source address points at a provider/registry that does not exist, or Terraform could not reach the registry at all (network, proxy, air-gap). Nothing has been installed yet — this is purely the metadata lookup.

Common Causes

1. Conflicting version constraints across modules. The root module and a child module pin incompatible ranges (e.g. < 5.0.0 vs >= 5.20.0), so the intersection is empty.
2. Wrong or legacy source address. A bare provider name (pre-0.13 style) or a typo’d source resolves to a provider that does not exist on the registry.
3. No matching version exists. The constraint requests a version that was never published or was removed/yanked.
4. Registry unreachable. DNS failure, corporate proxy, firewall, or a fully air-gapped environment with no mirror configured.
5. Stale .terraform.lock.hcl. The lock pins a version that conflicts with a newly tightened constraint, so the query can’t find a candidate that satisfies both.
6. Private/mirror registry auth. A private registry returns 401/403 because credentials in the CLI config or TF_TOKEN_* env var are missing or expired.

How to Reproduce the Error

Create a configuration with contradictory constraints and run init:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.20.0, < 5.0.0"
    }
  }
}

terraform init

Terraform queries the registry, finds the intersection >= 5.20.0, < 5.0.0 is empty, and emits “Failed to query available provider packages”.

Diagnostic Commands

# Confirm Terraform version (constraint behavior differs across majors)
terraform version

# Re-run init with full HTTP/registry tracing to see the failing request
TF_LOG=DEBUG terraform init 2>&1 | grep -iE 'registry|provider|discovery'

# Show every provider requirement and where it comes from
terraform providers

# Test raw registry reachability (DNS, proxy, TLS)
curl -sS https://registry.terraform.io/.well-known/terraform.json

# Inspect what the lock file currently pins
grep -A3 'provider "' .terraform.lock.hcl

terraform providers is the key command for constraint conflicts: it prints a tree of every module and the version range each one demands, so the contradiction becomes obvious.

Step-by-Step Resolution

1. Read the failing constraint. The error prints the combined range (e.g. >= 5.20.0, < 5.0.0). If it is contradictory, the problem is constraint reconciliation, not the network.

2. Map constraints to their source modules.

   terraform providers

   Find which module pins the offending range and relax or align it.

3. Reconcile required_providers. Pick a single compatible range. Avoid upper-bound pins that fight newer modules:

   terraform {
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = "~> 5.40"
       }
     }
   }

4. Verify the source address. It must be NAMESPACE/NAME (e.g. hashicorp/aws), not a bare name. For partner/community providers, copy the exact source from the registry page.

5. Regenerate the lock file if it is stale.

   rm .terraform.lock.hcl
   terraform init -upgrade

   -upgrade ignores existing locks and re-selects the newest versions that satisfy the constraints.

6. Fix network / proxy / air-gap. If the registry is unreachable, set the proxy or configure a mirror:

   export HTTPS_PROXY=http://proxy.corp.internal:3128
   export NO_PROXY=.corp.internal

   For air-gapped runners, use a filesystem mirror in ~/.terraformrc:

   provider_installation {
     filesystem_mirror {
       path    = "/opt/terraform/providers"
       include = ["registry.terraform.io/*/*"]
     }
     direct {
       exclude = ["registry.terraform.io/*/*"]
     }
   }

7. Authenticate to private registries.

   export TF_TOKEN_app_terraform_io="xxxxxxxx.atlasv1.yyyy"
   terraform init

Prevention and Best Practices

• Use pessimistic constraints (~> 5.40) over hard upper bounds (< 6.0.0) so child modules can move forward without conflicting.
• Commit .terraform.lock.hcl so CI installs the same versions, and refresh it deliberately with terraform init -upgrade in a reviewed PR.
• Run terraform providers whenever you add a module to catch constraint drift early.
• For air-gapped or rate-limited estates, stand up a provider mirror and point provider_installation at it so init never depends on the public registry.
• Keep source addresses fully qualified and pinned to the exact namespace shown on the Terraform Registry.

Related Errors

• Terraform Error: Failed to install provider
• Terraform Error: error configuring provider
• Terraform Error: Invalid for_each argument

Frequently Asked Questions

Why does the error show two contradictory constraints joined together? Terraform merges every constraint from every module into one combined range. >= 5.20.0, < 5.0.0 means one module wants at least 5.20 and another caps below 5.0 — the intersection is empty, so no version qualifies.

Does terraform init -upgrade fix a network failure? No. -upgrade only changes version selection by ignoring the lock file. If the registry is unreachable (DNS, proxy, air-gap), you must fix connectivity or configure a mirror first.

The provider exists on the registry but Terraform says it does not — why? Almost always a wrong source address: a bare name like aws instead of hashicorp/aws, or a typo in the namespace. Copy the exact address from the provider’s registry page.

How do I find which module is pinning the bad version? Run terraform providers. It prints a tree of modules with each one’s required version range, so you can see exactly which child module introduces the conflicting constraint.

Can a stale lock file cause this even when my constraints are fine? Yes. If you tighten a constraint but the lock still pins an out-of-range version, the query can fail to find a candidate. Delete .terraform.lock.hcl and run terraform init -upgrade to regenerate it.