Terraform Init Registry Timeout: Diagnose CI Failures

DEV Community

terraform init registry timeout ci: four layers, one message

A terraform init registry timeout ci failure prints one diagnostic assembled from four separate error messages, each added by a different layer as the failure travelled up, and the useful one is at the bottom. Read from the top and you will conclude the provider is missing; read from the bottom and you will see that a TCP connection or a TLS handshake never completed. Four layers each add a clause, so the message reads back to front. The right panel carries the two defaults that decide how long a registry failure takes to report and how many attempts it makes. What this error means The Finding versions matching ... line is followed by a diagnostic headed Failed to query available provider packages, then a body that nests several clauses separated by colons, then a suggestion to run terraform providers. The summary line is the same for every failure in this family, including a provider name that does not exist, so it carries no diagnostic value on its own. The clause worth finding is the second one. could not connect to means service discovery failed, so Terraform never learned where the registry's provider endpoints are. could not query provider registry for means discovery succeeded and the versions call failed. failed to query provider mirror means you are on a network mirror and possibly did not know it. ```Captured locally on Terraform v1.14.8, 2026-09-21, against a local listener that accepts and never answers. Not runner output Error: Failed to query available provider packages Could not retrieve the list of available versions for provider localhost:8946/hashicorp/random: could not connect to localhost:8946: failed to request discovery document: Get "https://localhost:8946/.well-known/terraform.json": net/http: TLS handshake timeout To see which modules are currently depending on localhost:8946/hashicorp/random and what versions are specified, run the following command: terraform providers

Common causes

TLS interception in the egress path

A proxy that terminates TLS to inspect it will either present a certificate Terraform does not trust or stall the handshake under load. The handshake timeout clause is the signature, because it proves a TCP connection was made: the packets are reaching something, and that something is not completing the negotiation. Nothing about the registry is implicated.

Every job runs terraform init and downloads every provider

Without a plugin cache, each job in each workflow fetches the full provider set again, which for a stack with several large providers is hundreds of megabytes per run. That is both the slowest part of the pipeline and the part most exposed to a network blip, and it grows with the matrix rather than with the codebase.

A CLI configuration file redirects you to a mirror you forgot about

A provider_installation block in the CLI configuration, inherited from an image or an organisation default, sends every lookup to a network mirror. When that mirror is slow or partly populated, the failure names the mirror rather than the registry, which is the clue, and in our experience the response to that clue is usually surprise that a mirror was configured at all.

The registry is genuinely having a bad few minutes

It happens, and it is the case the default of two attempts is least equipped for. The distinguishing feature is that the bottom clause is a 5xx status or a read timeout rather than a connection or handshake failure, and that a re-run a few minutes later succeeds with nothing changed. This is the only one of these four where retrying the job is the correct response.

How to fix it

Cache providers so init stops being a network operation

1. Set TF_PLUGIN_CACHE_DIR to a path inside the workspace and create it before init runs, because Terraform will not create it for you and silently skips caching if it is missing.
2. Cache that directory across runs, keyed on the dependency lock file so the key moves exa...
   
   Powered by Readybot.io