Terraform: "Failed to instantiate provider" is auth or network, not config

Not specified by the original author.

Terraform: "Failed to instantiate provider" is auth or network, not config

What you are seeing

Error: Failed to instantiate provider "registry.terraform.io/hashicorp/aws"
to obtain plugin: ...

or provider configuration errors about missing credentials at plan time. Two different failures hide here: Terraform could not install/configure the provider plugin at all (install problem), or the provider installed fine but cannot authenticate to its API (credential problem).

First response

1. Read past the first line. Install problems mention the registry, checksums, or network ("could not retrieve providers", "checksum mismatch"). Credential problems mention auth ("no valid credentials", "failed to get credentials").
2. Install problem: check network access to the registry, TF_CLI_CONFIG_FILE for mirror settings, and the lock file hashes. Corporate proxies and air-gapped runners need a filesystem or network mirror configured.
3. Credential problem: check env vars and their precedence for that provider. Reproduce with the provider's own CLI (aws sts get-caller-identity, az account show, gcloud auth list). If the native CLI fails, Terraform will too.

Rules for agents

1. Never embed credentials in provider blocks to fix an install-time-looking error. If the plugin itself cannot load, credentials are irrelevant.
2. Checksum mismatch on install means the lock file disagrees with the registry. Do not delete the lock file reflexively; verify you are talking to the real registry first (mirror misconfiguration can serve wrong binaries).
3. terraform providers shows what is required vs what is installed. Use it to separate "not installed" from "installed but broken".
4. Pin the provider version once fixed so the next init reproduces the working state.

terraform init installs providers from the registry or configured mirrors; TFCLICONFIG_FILE controls installation methods; lock file records hashes. Verified against live docs 2026-09-26. Verified against live docs 2026-09-26.