🚨 Terraform Error Guide: 'Failed to install provider' (checksum mismatch) on init

Exact Error Message

This fires during terraform init after version selection succeeds — the download or verification step is what fails. The most common form is a checksum mismatch against the lock file:

Error: Failed to install provider

Error while installing hashicorp/aws v5.40.0: the local package for
registry.terraform.io/hashicorp/aws 5.40.0 doesn't match any of the
checksums previously recorded in the dependency lock file (this might
be because the available checksums are for packages targeting different
platforms)

Two other variants point at a corrupted download or a registry/query failure during install:

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: 503 Service Unavailable

Error: Failed to install provider

Error while installing hashicorp/random v3.6.0: open
.terraform/providers/.../terraform-provider-random_v3.6.0_x5: no space left on device

What the Error Means

Version selection picked a provider, but downloading or verifying its package failed. The “checksum does not match” variant is the most misunderstood: .terraform.lock.hcl records SHA256 hashes per platform. If the lock was generated on macOS (darwin_arm64) and CI runs on linux_amd64, the lock has no hash for the package Terraform just downloaded — so it refuses to trust it. Other variants mean the download was corrupted, the plugin cache is stale, the registry was unreachable mid-install, a GPG signature failed, or the local .terraform/providers directory is out of disk or not writable.

Common Causes

1. Lock file missing the current platform’s hash. The lock was generated on a different OS/arch and only contains hashes for other platforms.
2. Corrupted or truncated download. A flaky connection produced a partial zip whose hash differs from the registry’s recorded checksum.
3. Stale or shared plugin cache. TF_PLUGIN_CACHE_DIR holds a bad or partial copy that Terraform keeps reusing.
4. Registry/network failure mid-install. A 5xx, timeout, or proxy reset interrupts the package or checksum retrieval.
5. GPG/signature verification failure. The provider’s signing key isn’t trusted, or the signature didn’t validate (common with self-hosted mirrors).
6. Disk space or permission problems. .terraform/providers cannot be written — full disk, read-only mount, or wrong ownership in CI.

How to Reproduce the Error

Generate a lock file for one platform only, then init on another:

# On a macOS workstation, record hashes for darwin only
terraform providers lock -platform=darwin_arm64
git add .terraform.lock.hcl && git commit -m "lock" && git push

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.40"
    }
  }
}

# In linux_amd64 CI, init now fails because the lock has no linux hash
terraform init

Diagnostic Commands

# Which platforms are recorded in the lock file
grep -A12 'provider "registry.terraform.io/hashicorp/aws"' .terraform.lock.hcl

# Full install trace: see the download URL, retries, and checksum compare
TF_LOG=TRACE terraform init 2>&1 | grep -iE 'checksum|install|download|signature'

# Confirm the registry and package URLs are reachable
curl -sSI https://releases.hashicorp.com/terraform-provider-aws/

# Check disk space and write permissions on the install target
df -h .
ls -ld .terraform/providers

# Show the active plugin cache directory, if any
echo "$TF_PLUGIN_CACHE_DIR"

Step-by-Step Resolution

1. Add hashes for every platform you run on. This is the correct fix for the checksum-mismatch variant — do not delete the lock to “make it work”:

   terraform providers lock \
     -platform=linux_amd64 \
     -platform=darwin_arm64 \
     -platform=windows_amd64

   Commit the updated .terraform.lock.hcl so every platform’s hash is present.

2. Clear a corrupted download and re-init. If the package is truncated rather than cross-platform:

   rm -rf .terraform
   terraform init

   This removes the partial provider and downloads a fresh copy.

3. Purge a poisoned plugin cache. A shared cache can serve a bad artifact repeatedly:

   rm -rf "$TF_PLUGIN_CACHE_DIR"/registry.terraform.io/hashicorp/aws
   terraform init

4. Retry transient registry failures. For 5xx/timeout variants, retry and confirm the proxy isn’t rewriting responses:

   TF_LOG=DEBUG terraform init

5. Fix disk space and permissions. Free space or correct ownership on the working directory:

   df -h .
   chown -R "$(id -u):$(id -g)" .terraform

6. Use a verified mirror for air-gapped installs. Mirror the providers and point installation at them, which also pins trusted hashes:

   terraform providers mirror /opt/terraform/providers

   provider_installation {
     filesystem_mirror {
       path    = "/opt/terraform/providers"
       include = ["registry.terraform.io/*/*"]
     }
   }

7. Set a clean shared cache to speed future installs.

   export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
   mkdir -p "$TF_PLUGIN_CACHE_DIR"
   terraform init

Prevention and Best Practices

• Generate locks for all target platforms with terraform providers lock -platform=... whenever you change provider versions, and commit the result.
• Never delete .terraform.lock.hcl just to clear a checksum error — that discards security guarantees. Add the missing platform hash instead.
• Standardize the runner OS/arch across laptops and CI to minimize cross-platform hash gaps.
• Use a filesystem or network mirror for air-gapped or rate-limited estates so installs are deterministic and offline-safe.
• Point TF_PLUGIN_CACHE_DIR at a per-user (not world-shared) directory to avoid one bad artifact poisoning every workspace.

Related Errors

• Terraform Error: Failed to query available provider packages
• Terraform Error: error configuring provider
• Terraform Error: Invalid for_each argument

Frequently Asked Questions

Why does the checksum mismatch mention “different platforms”? The lock file stores per-platform SHA256 hashes. If it was generated on one OS/arch and you init on another, the downloaded package is legitimate but its hash isn’t in the lock yet. Run terraform providers lock -platform=<your-platform> to add it.

Is deleting .terraform.lock.hcl a safe fix? No. The lock exists to guarantee you install exactly the bytes you reviewed. Deleting it sidesteps the check and weakens supply-chain safety. Add the missing platform hash with terraform providers lock instead.

When should I delete .terraform versus the lock file? Delete .terraform (the local install directory) to clear a corrupted or partial download. Touch the lock file only to add platform hashes — never to silence a real mismatch.

How does TF_PLUGIN_CACHE_DIR cause install failures? If the cache holds a truncated or wrong artifact, Terraform reuses it on every init and keeps failing the checksum compare. Remove the offending provider directory from the cache, then re-init.

What does a 503 during install mean? The registry or release host was temporarily unavailable while fetching the package or its authentication checksums. Retry; if it persists, check a corporate proxy and consider a local mirror.