Error - Failed to Query Available Provider Packages does not match configured version constraint – HashiCorp Help Center

Introduction

When working with Terraform, you may encounter an error from "terraform init" indicating that provider versions do not match the configured version constraint. This article provides insights into understanding and resolving it.

Problem

When you run the terraform init command, the operation may fail with the following error message:

Error: Failed to query available provider packages

Could not retrieve the list of available versions for provider xxx/xxx: locked provider registry.terraform.io/xxx/xxx x.xx.x does not match configured version constraint ~> x.y.z, >= x.y.z, ~> x.y.z, < x.y.z; must use terraform init -upgrade to allow selection of new versions

Cause

This error occurs because a version constraint defined in your Terraform configuration conflicts between modules. Terraform enforces version constraints to maintain compatibility between modules and providers. When these constraints are violated, you may encounter this error.

Solutions

Here are several approaches to resolve this provider version conflict.

Solution 1: Upgrade Provider Versions with the `-upgrade` Flag

The error message suggests the most direct solution. The -upgrade flag allows Terraform to ignore the versions specified in the lock file and select the newest provider version that complies with the version constraints in your configuration.

Run terraform init with the -upgrade flag.

$ terraform init -upgrade

This flag allows Terraform to update provider versions according to your constraints.

Note: Upgrading/downgrading a provider version may alter resource arguments or configurations, potentially breaking existing code.

Solution 2: Manually Align Provider Version Constraints

If upgrading is not desirable or does not resolve the issue, you may need to manually align the provider version constraints across your modules.

Review Provider Configurations: Examine the required_providers blocks in your root module and any child modules. Identify the conflicting version constraints for the provider mentioned in the error.
Ensure Consistency: Modify the version constraints in your modules to use a compatible version range. Often, this means ensuring all modules allow for a common, acceptable provider version.
Test Incrementally: If you are unsure which module is causing the conflict, add modules to your root configuration one by one and run terraform init after each addition. This process can help isolate the incompatible module.

Solution 3: Adopt Provider Version Best Practices

To prevent this issue in reusable modules, follow HashiCorp's best practices for provider versioning. Specify a minimum provider version in shared modules, but do not constrain the maximum version. Allow the root module to define the upper version limit.

Do not use ~> (or other maximum-version constraints) for modules you intend to reuse across many configurations, even if you know the module isn't compatible with certain newer versions. Doing so can sometimes prevent errors, but more often it forces users of the module to update many modules simultaneously when performing routine upgrades. Specify a minimum version, document any known incompatibilities, and let the root module manage the maximum version.

By following this practice, you centralize control over provider upgrades in the root configuration, reducing the likelihood of conflicts between modules.

Outcome

After applying one of the solutions, the terraform init command should complete successfully, indicating that Terraform has found and installed provider versions that satisfy all configuration constraints.

Additional Information