Terraform "Failed to install provider" - Fix Registry Errors

terraform init could not download a provider plugin. Most often the registry was briefly unreachable, the provider source is wrong, or the runner has no route to the registry.

What this error means

terraform init aborts while installing providers, printing "Failed to install provider" with a registry error. A transient network blip clears on retry; a wrong source address fails every time.

terraform init output

Error: Failed to install provider

Error while installing hashicorp/aws v5.40.0: could not query provider registry
for registry.terraform.io/hashicorp/aws: failed to retrieve authentication
checksums for provider: 504 Gateway Timeout

Common causes

Transient registry or network failure

A 5xx from registry.terraform.io or a brief network drop interrupts the plugin download. These are flaky and usually succeed on a second init.

Wrong provider source address

A typo in source (e.g. hashicorp/awss) or an org that does not host the provider makes the registry lookup fail deterministically.

No network path to the registry

On an air-gapped or proxied runner there may be no route to registry.terraform.io, so every plugin download fails until a mirror or proxy is configured.

How to fix it

Retry, then verify the source address

Re-run init; if it persists, confirm every required_providers source is spelled correctly and the version exists.

Terminal

terraform init -upgrade
# confirm the source/version exists
terraform providers

Use a provider mirror behind a proxy

On restricted runners, mirror providers to a filesystem or network location and point Terraform at it.

.terraformrc

terraform providers mirror ./vendor/providers
# .terraformrc or env CLI config
provider_installation {
  filesystem_mirror { path = "./vendor/providers" }
}

Cache the plugin directory between runs

Set a plugin cache so re-runs reuse already-downloaded providers and depend less on the registry.