⚙️ OpenTofu Error: Provider Checksum Mismatch in the Dependency Lock File

Exact Error Message

╷
│ Error: Failed to install provider
│
│ Error while installing hashicorp/aws v5.60.0: the local package for
│ registry.opentofu.org/hashicorp/aws 5.60.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); for more information see the "Checksum verification" section
│ in the OpenTofu documentation.
╵

You may also see the current package for ... does not match any of the checksums recorded in the dependency lock file during tofu init.

What It Means

OpenTofu records a cryptographic checksum for every provider package in .terraform.lock.hcl the first time you install it. On later runs it re-verifies that the downloaded package matches one of the recorded hashes. When the hash it computes is not in the lock file, init aborts to protect you from an unexpected or tampered package.

Most of the time this is not an attack — it is a platform or version drift. Lock files can record hashes for only the platforms you have initialized on, so a Linux CI runner may reject a lock file that was written on a macOS laptop.

Common Causes

• The lock file was generated on one OS/architecture and reused on another (macOS darwin_arm64 locally, Linux linux_amd64 in CI) without cross-platform hashes.
• The provider version was bumped in required_providers but the lock file still holds the old version’s hashes.
• The lock file is out of date after switching provider registries or mirrors.
• A partially downloaded or corrupted provider in the plugin cache.
• A genuinely different package served by a proxy, mirror, or private registry.

Diagnostic Commands

Show what version and hashes are currently locked:

cat .terraform.lock.hcl

Try a normal init to reproduce the exact mismatch:

tofu init

Check which platforms and versions your config requires:

tofu providers

Inspect the version reported so you know which release you are pulling:

tofu version

Step-by-Step Resolution

1. Confirm the version in .terraform.lock.hcl matches your required_providers constraint. If you just bumped a version, the old hashes are expected to fail.

2. Regenerate the lock file for every platform your team and CI use. This is the correct fix for the platform-mismatch case:

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

3. Commit the updated lock file so all environments share the same verified hashes:

git add .terraform.lock.hcl && git commit -m "Add multi-platform provider hashes"

4. If the plugin cache is corrupt, clear it and re-init cleanly:

rm -rf .terraform
tofu init

5. As a last resort when you trust the source (for example, a version you deliberately upgraded), let init add the new hashes:

tofu init -upgrade

6. Confirm the mismatch is gone:

tofu init

OpenTofu has been successfully initialized!

Never bypass verification for a package you cannot account for — a mismatch you did not expect is exactly the signal the lock file exists to raise.

Prevention

• Always run tofu providers lock with every platform your developers and CI runners use, so the lock file is complete before it hits pipelines.
• Commit .terraform.lock.hcl to version control; it is meant to be shared, not gitignored.
• Bump provider versions deliberately with tofu init -upgrade, then commit the refreshed hashes in the same change.
• Use a single, consistent provider registry or mirror across all environments.
• Pin provider versions in required_providers so upgrades are explicit and reviewable. A quick review with the OpenTofu upgrade prompts can help audit constraints before a bump.

Related Errors

• Failed to install provider (network/platform) — the package could not be fetched at all, versus fetched-but-mismatched here.
• Failed to query available provider packages — registry discovery failed before checksums are even compared.
• Inconsistent dependency lock file — the lock file lacks an entry for a provider your config now requires.
• Unsupported provider plugin protocol version — the package installed but is built for an incompatible plugin protocol.

Frequently Asked Questions

Is a checksum mismatch a security problem? It can be, which is why init refuses to continue; but in practice it is usually a platform or version drift in the lock file rather than a tampered package.

Why does it only fail in CI and not on my laptop? Your lock file likely only records hashes for your local platform; CI runs on a different OS/architecture whose hash is missing. Regenerate with tofu providers lock for all platforms.

Should I delete .terraform.lock.hcl to fix this? No — deleting it discards the verification baseline. Regenerate it with tofu providers lock or refresh it with tofu init -upgrade and commit the result.

When is tofu init -upgrade safe? When you intentionally changed the provider version and trust the source; it re-records the new hashes rather than silently ignoring the check. For more provider and lock-file fixes, see the OpenTofu guides.