Terraform Provider Checksum Mismatch Fixer

The Incident (What Does the Error Mean?)

Raw error output from a failing terraform init:

Error: Failed to install provider

Error while installing hashicorp/aws v5.31.0: the current package for
registry.terraform.io/hashicorp/aws 5.31.0 doesn't match any of the
checksum values previously recorded in the dependency lock file.

For more context, see:
  https://www.terraform.io/language/files/dependency-lock

Or the variant thrown when a cached zip is corrupt:

Error: Failed to install provider from shared cache

Error while installing hashicorp/google v5.10.0 from the shared cache
directory: the provider package in the cache at
.terraform/providers/.../google_5.10.0_linux_amd64.zip
has a hash that doesn't match any recorded in the lock file:
  got:  zh:8abc1234...
  want: zh:deadbeef...

Immediate consequence: terraform init exits non-zero. No plan, no apply, no pipeline. Every downstream job — PR validation, scheduled drift detection, emergency hotfixes — is dead until this is resolved.

The Attack Vector / Blast Radius

This error has two completely different causes with wildly different blast radii. Conflating them is how teams waste hours.

Cause A — Benign: Stale or platform-incomplete lock file (95% of cases)

Your .terraform.lock.hcl was committed on macOS (darwin_amd64) but CI runs on linux_amd64. The lock file only contains h1: hashes for the Darwin zip. When the Linux runner downloads the Linux zip, its hash is absent from the lock file. Terraform refuses to proceed. This is a workflow problem, not a security incident.

Cause B — Critical: Supply-chain substitution or mirror tampering (5% of cases, treat as P0)

If the hash mismatch occurs on the same platform that originally generated the lock file, and you have not changed the provider version, this is a red flag for:

• A compromised internal Artifactory/Nexus mirror serving a modified binary.
• A DNS hijack redirecting registry.terraform.io to a malicious mirror.
• A CI runner with a poisoned shared provider cache (.terraform/providers/ or TF_PLUGIN_CACHE_DIR).

A tampered provider binary executes with full credentials available to Terraform — your AWS keys, GCP service account, Vault tokens. It can exfiltrate credentials, create backdoor IAM users, or destroy resources. The blast radius is your entire cloud estate.

Before you run any fix: verify the expected hash against the official registry.

# Cross-check the legitimate SHA256 from HashiCorp's registry API
curl -s https://registry.terraform.io/v1/providers/hashicorp/aws/5.31.0/download/linux/amd64 \
  | python3 -m json.tool | grep shasum

If the hash the registry returns matches what Terraform downloaded but not what's in your lock file → Cause A. If the hash Terraform downloaded does not match the registry → treat as a security incident, rotate all credentials, and audit your network path.

Prevention in CI/CD

1. Enforce lock file freshness with a pre-commit hook

# .git/hooks/pre-commit (or use pre-commit framework)
#!/bin/bash
if git diff --cached --name-only | grep -q 'versions.tf\|\.tf$'; then
  terraform providers lock \
    -platform=linux_amd64 \
    -platform=darwin_arm64 \
    2>/dev/null
  git add .terraform.lock.hcl
fi

2. Checkov policy to block unpinned providers

checkov -d . --check CKV_TF_1  # Ensures all modules use pinned hashes

3. OPA/Conftest policy to enforce exact version pinning

# policy/terraform_provider_pin.rego
package terraform.providers

deny[msg] {
  provider := input.configuration.provider_config[_]
  not regex.match(`^= \d+\.\d+\.\d+$`, provider.version_constraint)
  msg := sprintf(
    "Provider '%v' must use an exact version pin (= X.Y.Z), got: %v",
    [provider.name, provider.version_constraint]
  )
}

# Run in CI
terraform show -json tfplan.json | conftest test - --policy policy/

4. Dependabot / Renovate for automated provider version bumps

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: terraform
    directory: "/"
    schedule:
      interval: weekly
    # Renovate: set rangeStrategy to "pin" to force exact pins

5. Verify provider GPG signatures in your pipeline (defense against Cause B)

# Download and verify the shasums signature before terraform init
PROVIDER_VERSION="5.31.0"
OS="linux"
ARCH="amd64"
BASE_URL="https://releases.hashicorp.com/terraform-provider-aws/${PROVIDER_VERSION}"

curl -sO "${BASE_URL}/terraform-provider-aws_${PROVIDER_VERSION}_SHA256SUMS"
curl -sO "${BASE_URL}/terraform-provider-aws_${PROVIDER_VERSION}_SHA256SUMS.sig"

# Import HashiCorp's signing key (do this once in your base image)
gpg --recv-keys 34365D9472D7468F

# Verify
gpg --verify \
  "terraform-provider-aws_${PROVIDER_VERSION}_SHA256SUMS.sig" \
  "terraform-provider-aws_${PROVIDER_VERSION}_SHA256SUMS" \
  && echo "Signature VALID" || (echo "SIGNATURE INVALID — POSSIBLE SUPPLY CHAIN ATTACK" && exit 1)

Run this check before terraform init in any pipeline that touches production. A failed GPG verification is a security incident, not a config error.