Terraform "Inconsistent dependency lock file": what to run, and what to commit

1. You added a provider: init

The message above is the simple case. You, or a colleague who just pushed, added a provider or a module that needs one:

terraform init
git add .terraform.lock.hcl
git commit -m "Add the aws provider to the lock file"

The same happens when the lock file was never committed, or the local .terraform folder is out of date.

2. You changed the version: init -upgrade

Error: Failed to query available provider packages

Could not retrieve the list of available versions for provider hashicorp/aws:
locked provider registry.terraform.io/hashicorp/aws 5.31.0 does not match configured version constraint ~> 6.0; must use terraform init -upgrade to allow selection of new versions

The lock file holds 5.31.0, and your configuration now asks for 6.x. A plain init deliberately won’t change a locked version, so you have to ask:

terraform init -upgrade
git diff .terraform.lock.hcl

Read the diff. -upgrade moves every provider to the newest version its constraint allows, not only the one you edited, so review the plan closely:

terraform plan

Major versions can change behavior, so read the provider’s upgrade guide first. To undo, restore the old file with git checkout .terraform.lock.hcl, and run terraform init again.

3. Checksums: another platform

Error: Failed to install provider

Error while installing hashicorp/aws v6.0.0: the local package for
registry.terraform.io/hashicorp/aws 6.0.0 doesn't match any of the checksums previously recorded in the dependency lock file

This classic one comes from people using different systems. By default, init only records checksums for the platform you ran it on. If a colleague works on an Apple silicon Mac, and CI runs on Linux, then the file doesn’t list the package CI needs.

Record every platform you use, and commit the result:

terraform providers lock \
  -platform=linux_amd64 \
  -platform=linux_arm64 \
  -platform=darwin_arm64 \
  -platform=windows_amd64
git add .terraform.lock.hcl
git commit -m "Record provider checksums for all platforms"

This downloads each package and takes a little while, but only needs repeating when versions change.

4. Checksums: a shared plugin cache

TF_PLUGIN_CACHE_DIR saves downloading the same provider repeatedly. But a cached package also only matches one platform’s checksums, so it can cause the same error. On a CI runner, use the providers lock above. Don’t reach for this setting without need:

export TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE=true

Its name is the warning: it lets Terraform skip the check.

If the checksum differs with the same version and the same platform, stop and find out why. That’s what the check exists to catch. A package that changed from what you recorded could be a problem at the source, so don’t just delete the file and move on.

5. A merge conflict in the lock file

Two branches updated providers, so don’t solve this by hand. Take either version of the file, then regenerate:

git checkout --theirs .terraform.lock.hcl
terraform init
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64
git add .terraform.lock.hcl

Then check the versions in the diff are the ones you expect.

6. Commit it, and make CI strict

Put it in git, and ignore only the folder:

.terraform/
*.tfstate
*.tfstate.*

Note that .terraform/ and .terraform.lock.hcl differ, and the first is the one to ignore. Don’t ignore the lock file, though older templates often do. The .gitignore Generator has a correct Terraform preset.

In a pipeline, make sure that the file isn’t changed quietly. With this flag, init fails instead of updating it:

terraform init -lockfile=readonly
terraform plan

Then a mismatch stops the run, and someone updates the file on purpose. Modules aren’t in the lock file, only providers, so pin those yourself with an exact version, or a Git tag.

7. OpenTofu

OpenTofu uses the same file, with the same commands. But it downloads from its own registry, registry.opentofu.org, and the file records that address. So after moving from Terraform, the entries don’t match:

tofu init -upgrade
tofu providers lock -platform=linux_amd64 -platform=darwin_arm64

Commit the result. And if a team mixes both tools on one project, expect the file to keep changing, so pick one.