Fix OpenTofu Registry Timeout Errors

Introduction

If tofu init or tofu plan fails with Client.Timeout exceeded while awaiting headers, OpenTofu could not fetch providers from registry.opentofu.org within the default HTTP timeout. Below are the root causes, the most effective fix, and additional ways to prevent the error.

Problem

The exact error message looks like this:

$ tofu init
Initializing the backend...
Initializing provider plugins...
- Finding hashicorp/aws versions matching ">= 4.0.0"...
Error: Failed to query available provider packages
Could not retrieve the list of available versions for provider
hashicorp/aws: could not query the registry: Get
"https://registry.opentofu.org/v1/providers/-/aws/versions":
Client.Timeout exceeded while awaiting headers

The timeout occurs when OpenTofu sends an HTTP request to the registry but does not receive the complete response headers within the built-in 60-second timeout. The registry is unreachable, slow, or the network path has issues.

Root Causes

• Slow or congested internet connection. Large provider downloads or high latency can trip the 60-second timeout.
• Firewall or proxy interfering. Corporate networks often throttle or block outbound HTTPS to unknown registries. A misconfigured HTTPS_PROXY environment variable can also hang the connection.
• DNS resolution delays. If DNS takes more than a few seconds to resolve registry.opentofu.org, the request may time out.
• Registry overload. The public OpenTofu registry sometimes experiences high load, especially after a new provider version release.

Solution

Increase the HTTP timeout

Set the OPENTOFU_HTTP_TIMEOUT environment variable to a higher value (in seconds). This is the single most reliable fix for this error. For example, 120 seconds:

$ export OPENTOFU_HTTP_TIMEOUT=120
$ tofu init

Add this line to your shell profile (~/.bashrc or ~/.zshrc) to make it permanent. OpenTofu v1.7.0 and later support this variable. If you still see timeouts, try 300.

Additional quick checks

• Verify connectivity to the registry:

  $ curl -v https://registry.opentofu.org/.well-known/terraform.json

shell
If that hangs, inspect your proxy environment variables:

  $ echo $HTTP_PROXY $HTTPS_PROXY

If they are set incorrectly, unset them:

  $ unset HTTP_PROXY
  $ unset HTTPS_PROXY
  $ tofu init

hcl

• Enable the shared plugin cache to avoid re-downloading providers. Add to ~/.opentofu/config.tfrc:

  plugin_cache_dir = "$HOME/.opentofu.d/plugin-cache"

Then run tofu init. Provider binaries are cached locally; subsequent init calls use the cache if the version matches.

• If the OpenTofu registry is temporarily down, change your provider source to hashicorp/aws (defaults to registry.terraform.io). OpenTofu v1.6+ supports the Terraform registry natively when the source does not include a hostname.

• For persistent problems, set up a network mirror in your organization. Configure ~/.opentofu/config.tfrc:
  

  provider_installation {
    network_mirror {
      url = "https://terraform-mirror.example.com/"
      include = ["*/*"]
    }
    direct {
      exclude = ["*/*"]
    }
  }

This offloads all provider downloads to your server, reducing external network dependency.

Prevention

To avoid registry timeouts long-term: set OPENTOFU_HTTP_TIMEOUT to at least 120 in CI/CD, deploy a shared plugin cache on build agents, run a local network mirror for high concurrency, and monitor registry.opentofu.org health with an external probe to switch to your mirror when latency spikes.

For a deeper comparison of OpenTofu and Terraform enterprise strategies, see OpenTofu vs Terraform: Enterprise Migration Math 2026.