🚨 OpenTofu Error: 'Failed to query available provider packages' — Cause, Fix, and Troubleshooting Guide

Overview

tofu init contacts a provider registry (by default registry.opentofu.org) to discover which versions of each required provider exist and where to download them. If OpenTofu cannot reach the registry, cannot resolve the address, or gets an error response, initialization stops:

Error: Failed to query available provider packages

Could not retrieve the list of available versions for provider
hashicorp/aws: could not connect to registry.opentofu.org: Failed to request
discovery document: Get "https://registry.opentofu.org/.well-known/terraform.json":
dial tcp: lookup registry.opentofu.org: no such host

Symptoms

• tofu init fails with Failed to query available provider packages.
• The detail line names a network problem: DNS failure, connection refused, TLS error, or HTTP 403/404.
• Works on a laptop with internet but fails on a locked-down or air-gapped CI runner.
• Sometimes reports “provider not found” for a mistyped source address.

Common Root Causes

• No network / DNS — the runner cannot resolve or reach registry.opentofu.org.
• Corporate proxy or firewall blocking the registry or the download CDN.
• Wrong source address — typo or a Terraform-only namespace not mirrored in the OpenTofu registry.
• Registry outage or rate limiting (HTTP 429).
• Air-gapped environment with no filesystem mirror configured.

How to diagnose

Read the detail line — it distinguishes DNS, TLS, and HTTP causes:

tofu init 2>&1 | sed -n '1,15p'

Test connectivity to the registry directly:

curl -sSI https://registry.opentofu.org/.well-known/terraform.json
nslookup registry.opentofu.org

Confirm the source addresses you declared:

grep -nA6 'required_providers' *.tf

Check whether a proxy is (or should be) set:

env | grep -i proxy

Fixes

Fix connectivity / proxy so the runner can reach the registry:

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
tofu init

Correct the source address to a valid registry namespace:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"   # resolves via registry.opentofu.org
      version = "~> 5.60"
    }
  }
}

Use a filesystem mirror in air-gapped setups. First, on a connected machine, mirror the providers:

tofu providers mirror /srv/tofu-providers

Then point OpenTofu at the mirror via CLI config (.tofurc):

provider_installation {
  filesystem_mirror {
    path = "/srv/tofu-providers"
  }
  direct { exclude = ["*/*"] }
}

Retry on transient outages/429 with a short backoff before failing the pipeline.

What to watch out for

• The detail line, not the headline, tells you the real cause — always read past the first line.
• Air-gapped CI needs a filesystem_mirror or network_mirror; direct registry access will never work there.
• Provider source addresses are case-insensitive but must be a real namespace; a typo looks like a network error.
• Cache the provider mirror in CI to avoid rate limits and speed up init.
• Set HTTPS_PROXY/NO_PROXY in the CI environment, not just your shell, or the runner still fails.

Related

• OpenTofu Error: ‘Inconsistent dependency lock file’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Invalid legacy provider address’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Module not installed’ — Cause, Fix, and Troubleshooting Guide