Problem
After you upgrade to Terraform v0.14 or newer, you may encounter a provider installation failure when running terraform init on a different platform (e.g., in HCP Terraform or Terraform Enterprise) than the one used to generate the .terraform.lock.hcl file.
Terraform 0.14 introduced the dependency lock file to track provider hashes, ensuring that Terraform installs the same dependency version each time you run terraform init. For a detailed overview, refer to the dependency lock file documentation.
When this issue occurs, you will see an error similar to the following:
Error: Failed to install provider Error while installing hashicorp/aws v3.22.0: the current package for registry.terraform.io/hashicorp/aws 3.22.0 doesn't match any of the checksums previously recorded in the dependency lock file
Cause
This error occurs if the dependency lock file was generated on a machine that uses a local provider plugin cache.
When the cache is already populated with the required provider version, Terraform generates a lock file containing only the h1: hash for that specific platform's provider package. It does not include the zh: hashes for all available platforms that the provider registry supplies. As a result, when you run terraform init on a different platform, the lock file lacks the necessary checksums for that platform, causing the installation to fail.
You can confirm this by inspecting the .terraform.lock.hcl file. The following example shows a lock file generated on macOS for the aws provider, which was found in the local cache. Note the absence of zh: hashes.
provider "registry.terraform.io/hashicorp/aws" {
version = "3.22.0"
constraints = ">= 3.20.0"
hashes = [
"h1:f/Tz8zv1Zb78ZaiyJkQ0MGIViZwbYrLuQk3kojPM91c=",
]
}Solution
To resolve this issue, you must update the dependency lock file to include hashes for all provider platforms.
Step 1: Update the Dependency Lock File
Run the terraform providers lock command to consult the source registries and add the missing zh: hashes to your .terraform.lock.hcl file.
$ terraform providers lock
After running the command, the lock file will be updated to include all registry-supplied zh: hashes while retaining the original h1: hash.
provider "registry.terraform.io/hashicorp/aws" {
version = "3.22.0"
constraints = ">= 3.20.0"
hashes = [
"h1:f/Tz8zv1Zb78ZaiyJkQ0MGIViZwbYrLuQk3kojPM91c=",
"zh:4a9a66caf1964cdd3b61fb3ebb0da417195a5529cb8e496f266b0778335d11c8",
"zh:514f2f006ae68db715d86781673faf9483292deab235c7402ff306e0e92ea11a",
"zh:5277b61109fddb9011728f6650ef01a639a0590aeffe34ed7de7ba10d0c31803",
"zh:67784dc8c8375ab37103eea1258c3334ee92be6de033c2b37e3a2a65d0005142",
"zh:76d4c8be2ca4a3294fb51fb58de1fe03361d3bc403820270cc8e71a04c5fa806",
"zh:8f90b1cfdcf6e8fb1a9d0382ecaa5056a3a84c94e313fbf9e92c89de271cdede",
"zh:d0ac346519d0df124df89be2d803eb53f373434890f6ee3fb37112802f9eac59",
"zh:d6256feedada82cbfb3b1dd6dd9ad02048f23120ab50e6146a541cb11a108cc1",
"zh:db2fe0d2e77c02e9a74e1ed694aa352295a50283f9a1cf896e5be252af14e9f4",
"zh:eda61e889b579bd90046939a5b40cf5dc9031fb5a819fc3e4667a78bd432bdb2",
]
}Step 2: Troubleshoot Potential Errors
In some cases, running terraform providers lock may produce the following error:
│ Error: Could not retrieve providers for locking │ │ Terraform failed to fetch the requested providers for linux_amd64 in │ order to calculate their checksums: │ some providers could not be installed: │ - registry.terraform.io/hashicorp/aws: │ the current package for │ registry.terraform.io/hashicorp/aws 3.22.0 doesn't match any of the │ checksums previously recorded in the dependency lock file.
This error occurs when the only hash present in the lock file is an h1: hash for a different platform than the one you are currently using. To resolve this, remove the .terraform.lock.hcl file and run the terraform providers lock command again.
Additional Information
This solution applies to any environment where you run Terraform configurations on multiple platforms. This is common in HCP Terraform and Terraform Enterprise, which perform runs on the linux_amd64 platform.
This operation works for any registry that implements the provider registry protocol. You can update in-house providers that are not on a public registry by specifying a filesystem or network mirror. For more details, refer to the documentation on lock entries for in-house providers.
For more details on the command, including how to lock providers for specific platforms, see the terraform providers lock command documentation.