⚙️ OpenTofu Error: 'Failed to request discovery document' registry service discovery

Exact Error Message

Initializing provider plugins...
╷
│ 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
╵

You may also see a TLS or proxy variant:

│ failed to request discovery document: Get ".../.well-known/terraform.json":
│ x509: certificate signed by unknown authority

What It Means

Before OpenTofu can download a provider or module, it performs service discovery: it fetches https://<registry-host>/.well-known/terraform.json to learn the registry’s API endpoints. Failed to request discovery document means OpenTofu could not complete that first HTTPS request to the registry host, so it never got far enough to list versions or download anything.

This is almost always an environment/networking problem between the machine running tofu init and the registry: DNS, a proxy, a firewall, or a TLS trust issue. It is not a problem with your configuration syntax.

Common Causes

• No outbound internet access from a CI runner or air-gapped host (firewall/egress rules).
• DNS resolution failure for registry.opentofu.org (or a custom registry host).
• A corporate HTTP/HTTPS proxy that OpenTofu is not configured to use.
• TLS interception by a proxy whose CA certificate is not in the system trust store.
• A private registry host misconfigured or missing its .well-known/terraform.json.
• A temporary registry outage or rate limiting.

Diagnostic Commands

Confirm the host resolves and is reachable:

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

Check the proxy environment OpenTofu will inherit:

env | grep -i proxy

Test TLS trust explicitly (surfaces intercepting CAs):

curl -vI https://registry.opentofu.org/.well-known/terraform.json 2>&1 | grep -i "SSL\|subject\|issuer"

Re-run init with debug logging:

TF_LOG=debug tofu init 2>&1 | grep -i "discovery\|registry\|proxy"

Step-by-Step Resolution

1. Establish whether it is DNS, connectivity, or TLS. If curl to the discovery URL fails the same way, the problem is the environment, not OpenTofu.

2. If a proxy is required, export it so OpenTofu’s HTTP client uses it, then re-init:

export HTTPS_PROXY=http://proxy.corp:3128
export NO_PROXY=localhost,127.0.0.1,.internal
tofu init

3. If a proxy intercepts TLS, add its CA to the system trust store (OpenTofu uses the OS trust bundle):

sudo cp corp-root-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
tofu init

4. If DNS is the issue, fix resolution or point at an internal mirror. For fully air-gapped hosts, configure a filesystem mirror so no discovery is needed:

# ~/.tofurc
provider_installation {
  filesystem_mirror {
    path    = "/opt/tofu/providers"
    include = ["registry.opentofu.org/*/*"]
  }
  direct {
    exclude = ["registry.opentofu.org/*/*"]
  }
}

5. For a private registry, verify the discovery document actually exists and returns valid JSON:

curl -sS https://tofu.registry.internal/.well-known/terraform.json

6. Re-run init and confirm providers resolve:

tofu init

Installing hashicorp/aws v5.60.0...
OpenTofu has been successfully initialized!

Prevention

• Allow-list the registry host(s) explicitly in CI egress rules and firewalls.
• Standardize proxy variables (HTTPS_PROXY, NO_PROXY) in the CI environment, not just on developer laptops.
• Distribute the corporate CA bundle to build agents so TLS interception does not break discovery.
• For air-gapped or high-reliability pipelines, mirror providers with a filesystem_mirror or a network mirror so init does not depend on the public registry.
• Commit .terraform.lock.hcl so a mirror can serve exact, pre-approved versions.

Related Errors

• Failed to install provider — discovery succeeded but the package download or checksum failed.
• Failed to download module — the same class of network/credential failure for a module source.
• x509: certificate signed by unknown authority — specifically a TLS trust gap, often from a proxy.
• no such host — a DNS resolution failure for the registry hostname.

Frequently Asked Questions

Is this a bug in my OpenTofu config? No. Discovery runs before any provider is parsed for correctness; this error is a network, DNS, proxy, or TLS problem in the environment.

How do I make init work behind a corporate proxy? Export HTTPS_PROXY (and NO_PROXY for internal hosts) and add the proxy’s CA to the system trust store, then re-run tofu init.

Can I run init with no internet at all? Yes, configure a filesystem_mirror in ~/.tofurc and pre-stage the provider packages so no registry discovery is attempted.

Why does curl to the well-known URL matter? It reproduces OpenTofu’s first request in isolation, so you can tell DNS, connectivity, and TLS failures apart quickly. See the prompt library for air-gapped mirror setups and more OpenTofu guides.