Fix Terraform "Error: Failed to query available provider packages" (Provider Not Found)

TL;DR

Terraform can't reach the provider registry, or it can't find a version matching your constraints. Start with terraform init -upgrade and test your network. Corporate proxy blocking HTTPS to the registry? Nine times out of ten, that's the real problem. Using a custom or private registry? Double-check the source address in required_providers.

What the Full Error Looks Like

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 a version constraint variation:

Error: Failed to query available provider packages

│ Could not retrieve the list of available versions for provider
│ hashicorp/azurerm: no available releases match the given constraints
│ >= 3.0.0,  3.114

Root Causes

• No internet access — Terraform can't reach registry.terraform.io
• Corporate proxy / firewall — HTTPS traffic to the registry is blocked
• Impossible version constraint — your required_providers block has conflicting or non-existent versions
• Wrong provider source address — typo or a leftover Terraform 0.12 implicit provider reference
• Stale lock file — .terraform.lock.hcl references a version that no longer exists or has a changed hash
• Private/custom registry unreachable — internal registry URL is wrong or missing credentials

Fix 1: Check Network Access to the Registry

Start here. Before touching any config, confirm your machine can actually reach the registry:

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

Timeout or connection error? That's a network problem — not a Terraform config issue.

Behind a Corporate Proxy

Set proxy environment variables before running terraform init:

# Linux/macOS
export HTTPS_PROXY=https://your-proxy.company.com:8080
export HTTP_PROXY=http://your-proxy.company.com:8080
export NO_PROXY="localhost,127.0.0.1"

terraform init

# Windows (PowerShell)
$env:HTTPS_PROXY = "https://your-proxy.company.com:8080"
$env:HTTP_PROXY = "http://your-proxy.company.com:8080"

terraform init

Fix 2: Run terraform init -upgrade

Stale lock file or outdated cached metadata? Force a full refresh:

terraform init -upgrade

This re-fetches provider metadata and writes fresh checksums to .terraform.lock.hcl. It won't touch your state.

Fix 3: Check Your required_providers Block

Open versions.tf — or wherever you keep your terraform block — and verify the source address and version constraint:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Make sure this version exists on the registry
    }
  }
  required_version = ">= 1.3.0"
}

Common mistakes:

• Using source = "aws" instead of source = "hashicorp/aws" — worked in Terraform 0.12, breaks in 0.13+
• Pinning to an exact patch like = 3.114.0 when it doesn't exist — use ~> 3.114 instead
• Conflicting constraints across modules — root requires >= 4.0 but a child module requires < 4.0

To see which versions actually exist for a provider:

curl -s https://registry.terraform.io/v1/providers/hashicorp/aws/versions | python3 -m json.tool | grep '"version"' | head -20

Fix 4: Delete the Lock File and Reinitialize

Corrupted lock file? Hash mismatch? Nuke it and start fresh:

rm .terraform.lock.hcl
rm -rf .terraform/
terraform init

Terraform resolves providers from scratch. Commit the regenerated lock file when done.

Fix 5: Use a Filesystem Mirror (Air-Gapped / Offline Environments)

No internet on your target machine? CI runners and air-gapped servers all hit this wall. The solution is a local provider mirror.

On a machine with internet access, download the providers:

terraform providers mirror /tmp/tf-mirror

Transfer the /tmp/tf-mirror directory to your target environment. Then tell Terraform to use it via ~/.terraformrc (Linux/macOS) or %APPDATA%/terraform.rc (Windows):

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

Fix 6: Private Registry Credentials

Private registries need credentials. Add them to ~/.terraformrc:

credentials "app.terraform.io" {
  token = "your-token-here"
}

Or use the environment variable for Terraform Cloud:

export TF_TOKEN_app_terraform_io="your-token-here"

Verify the Fix

A clean terraform init ends with:

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure.

Confirm the provider was actually downloaded:

ls .terraform/providers/registry.terraform.io/hashicorp/aws/

You should see a directory named after the provider version and platform — something like 5.40.0/linux_amd64/.

Quick Reference: Which Fix to Try First

• DNS error / no such host → Fix 1 (network/proxy)
• Hash mismatch / checksum error → Fix 2 (-upgrade) or Fix 4 (delete lock file)
• No available releases match constraints → Fix 3 (check version constraints)
• Air-gapped / no internet → Fix 5 (filesystem mirror)
• 401 Unauthorized from private registry → Fix 6 (credentials)