Failed to install provider after upgrading to Terraform 0.14

Introduction

Terraform 0.14 introduced the dependency lock file which will track the hashes
of providers used by the configuration, ensuring the same version of a
dependency is installed each time init is performed, even if a loose version
constraint is used.

For a detailed overview, including the types of hashing supported, please see
the documentation for this feature:
https://www.terraform.io/docs/configuration/dependency-lock.html

Problem

After upgrading your Terraform version to 0.14, and generating a dependency lock
file on a platform, for example your local macOS machine, an init performed on
a different platform, for example as a part of a TFC/TFE run, produces an error
similar to:

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

When the dependency lock file was generated on the first platform, Terraform
recorded the hashes it observed. For a brand new lock file, this is the h1:
hash of the platform’s version of the provider, and the zh: hashes of all the
versions available when the provider was sourced from the registry.

If the platform that generated the lock file made use of the provider plugin
cache
and the cache was already populated with the version that Terraform has
determined fulfills the version constraints, the lock file will only contain the
h1: hash for the platform’s version of the provider and not include the zh:
hashes that the registry supplies.

To confirm this is occurring, check the lock file’s contents.

In this example the lock file was generated on the macOS platform with Terraform
selecting the 3.22.0 version of the aws provider already in the provider
plugin cache. Terraform recorded the h1 hash of the cached provider but not
the zh hashes.

provider "registry.terraform.io/hashicorp/aws" {
  version     = "3.22.0"
  constraints = ">= 3.20.0"
  hashes = [
    "h1:f/Tz8zv1Zb78ZaiyJkQ0MGIViZwbYrLuQk3kojPM91c=",
  ]
}

Solution

The Terraform command, providers lock, can be used to update the lock file
after consulting the source registries in order to add any new registry supplied
hashes to the lock file.

Issuing the command when the lock file only contains the h1 hash of the
cached provider:

terraform providers lock

produces the lock file:

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",
  ]
}

Terraform added the zh hashes supplied by the registry while retaining the
originally observed h1 hash.

If when running the command you encounter the 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.

Remove the lock file before re-running the command. This issue is caused when the only hash present is a h1 for a different platform than the current one. When attempting to add the zh hashes to the existing lock entry, there needs to be a matching h1 hash for the current platform.

Please note that this example uses a provider sourced from the official
Terraform registry, registry.terraform.io. This operation will work for any
registry that implements the provider registry
protocol.

In-house providers that aren’t available on a registry can be updated similarly,
but will require the specifying of either a file system or network mirror. For
more details please see: https://www.terraform.io/docs/commands/providers/lock.html#lock-entries-for-in-house-providers

For more details including only locking specific platforms, please see the
documentation for this command:
https://www.terraform.io/docs/commands/providers/lock.html

Additional Information

This information applies to all environments where you are running configuration on multiple platforms. In the case of Terraform Cloud and Terraform Enterprise instances this will occur as the environments runs are perform on use the linux_amd64 platform.