**TL;DR:** "Failed to instantiate provider ... to obtain plugin" and provider auth errors at init mean the provider binary cannot be fetched or configured. Teaches separating install failures from credential failures. Read past the first line. Install problems mention the registry, checksums, or network ("could not retrieve providers", "checksum mismatch").

## The error

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

## The fix

**TL;DR:** "Failed to instantiate provider ... to obtain plugin" and provider auth errors at init mean the provider binary cannot be fetched or configured. Teaches separating install failures from credential failures. Read past the first line. Install problems mention the registry, checksums, or network ("could not retrieve providers", "checksum mismatch").

## The error

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

## 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.

## When to use this

- You are seeing this exact error message; match the block above, not just part of it.
- The failing call matches the scenario in the title: Terraform.
- You want the fastest verified fix before digging through logs.

## When not to use this

- Your error text differs from the block above; close cousins often have different causes.
- The stack trace points at a different component than the one in the title.
- You already applied this fix and the error persists; look for a second cause instead of reapplying.

## Also seen as

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