🚨 OpenTofu Error Guide: 'Inconsistent dependency lock file' — Reconcile the Provider Lock

Overview

OpenTofu records the exact provider versions and checksums it selected in .terraform.lock.hcl. On later runs it enforces that lock: if your configuration now requires a provider or version the lock does not cover, or the lock lacks a checksum for the current platform, tofu init refuses to proceed:

Error: Inconsistent dependency lock file

The following dependency selections recorded in the lock file are inconsistent with the current configuration:
  - provider registry.opentofu.org/hashicorp/aws: locked version selection 5.40.0 doesn't match the updated version constraints "~> 5.60"

To update the locked dependency selections to match a changed configuration, run:
  tofu init -upgrade

Symptoms

• tofu init (or plan/apply) fails with Inconsistent dependency lock file.
• The message lists a provider whose locked version no longer matches the required_providers constraint.
• A variant complains the lock has no matching checksum for the current platform (e.g., linux_amd64 in CI, darwin_arm64 locally).
• It appears after editing version constraints, adding a provider, or moving between macOS and Linux/CI.

Common Root Causes

• Version constraint changed — you tightened/loosened required_providers but did not update the lock.
• New provider added to the config with no entry in the lock file.
• Missing platform hashes — the lock was generated on one OS/arch and lacks checksums for CI’s platform.
• Lock file not committed — CI regenerates a different selection than local.
• Manual edits to .terraform.lock.hcl that left it internally inconsistent.

Diagnostic Workflow

Read exactly which provider/constraint is inconsistent:

tofu init 2>&1 | sed -n '1,30p'

Inspect the current lock selections and constraints:

cat .terraform.lock.hcl
grep -nA6 "required_providers" *.tf

Reconcile the lock with the configuration:

tofu init -upgrade

Ensure the lock carries checksums for every platform you run on (local + CI), so it is portable:

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

Confirm the result is clean and reproducible:

tofu init && tofu providers

Example Root Cause Analysis

A developer on an Apple Silicon Mac bumped the AWS provider constraint from ~> 5.40 to ~> 5.60, ran tofu init -upgrade locally, committed, and pushed. CI on linux_amd64 then failed with Inconsistent dependency lock file: the lock recorded a checksum for darwin_arm64 only.

The root cause was a platform-incomplete lock. tofu init -upgrade on the Mac recorded hashes for the developer’s platform but not for the Linux CI runners, so CI could not verify the provider it downloaded against the lock. The fix was to regenerate the lock with tofu providers lock listing every platform the project runs on (linux_amd64, darwin_arm64, linux_arm64) and commit the fuller lock. CI then found a matching checksum and initialized cleanly. The team added the multi-platform lock step to their release checklist to prevent recurrence.

Prevention Best Practices

• Always commit .terraform.lock.hcl to version control so local and CI select identical providers.
• Run tofu providers lock with every platform your team and CI use, so the lock is portable.
• After changing required_providers, run tofu init -upgrade and commit the updated lock in the same change.
• Never hand-edit the lock file; regenerate it.
• Pin providers with meaningful constraints and review lock diffs in code review.

Quick Command Reference

tofu init                                   # enforce the lock (reproduces error)
tofu init -upgrade                          # update lock to match constraints
tofu providers lock -platform=linux_amd64 -platform=darwin_arm64
cat .terraform.lock.hcl                     # inspect recorded selections
tofu providers                              # show provider requirements

Conclusion

Inconsistent dependency lock file means .terraform.lock.hcl and your configuration disagree — a changed constraint, an unlocked provider, or missing platform checksums. Run tofu init -upgrade to reconcile version selections, use tofu providers lock with every platform to make the lock portable across local and CI, and always commit the lock so every run resolves the same providers reproducibly.