🏗️ Terraform Error: 'no available provider ... matches constraints' Version Conflict

Exact Error Message

╷
│ Error: Failed to query available provider packages
│
│ Could not retrieve the list of available versions for provider
│ hashicorp/aws: no available releases match the given constraints
│ >= 4.0.0, < 5.0.0, >= 5.20.0
╵

A closely related form appears when two modules pin incompatible ranges:

│ Error: Unresolvable provider version constraints
│
│ The requested provider hashicorp/aws is required by:
│   root module (>= 5.20.0)
│   module.networking (~> 4.67)
│
│ No single version of hashicorp/aws satisfies all of these constraints.

What It Means

During terraform init, Terraform gathers every required_providers constraint from the root module and all child modules, intersects them, and then asks the registry for a provider version that satisfies the combined range. When the ranges do not overlap — for example one module wants AWS 4.x and another demands 5.20 or newer — the intersection is empty and there is no version to install. Terraform stops before downloading anything.

This is a dependency-resolution problem, not a network or registry outage. It usually surfaces after you bump a provider in one place, pull in a third-party module with its own pins, or upgrade Terraform and inherit stricter constraints.

Common Causes

• Two modules declare mutually exclusive ranges (~> 4.67 vs >= 5.20.0).
• A vendored or registry module pins an old major version that conflicts with the root.
• A stale .terraform.lock.hcl records a version outside the new constraints.
• A typo in a constraint (>= 5.20.0, < 5.0.0) that can never be satisfied.
• Requiring a version that does not exist yet in the registry (a future or yanked release).

Diagnostic Commands

See exactly which modules impose which constraints:

terraform providers

Attempt init to reproduce the resolution failure with full detail:

terraform init

Inspect the recorded versions and constraints in the lock file:

cat .terraform.lock.hcl

Search every module for the offending provider’s constraints:

grep -rn "hashicorp/aws\|version =" *.tf modules/

Step-by-Step Resolution

1. Read the terraform providers output. It prints the dependency tree and the constraint each module contributes, which pinpoints the conflict:

provider[registry.terraform.io/hashicorp/aws] >= 5.20.0
└── module.networking
    provider[registry.terraform.io/hashicorp/aws] ~> 4.67

2. Decide on a single overlapping range. If both modules can run on AWS 5.x, widen the old pin. Edit the conflicting module’s required_providers:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.20.0, < 6.0.0"
    }
  }
}

3. Align the root constraint so it clearly overlaps and pins a major version:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.60"
    }
  }
}

4. If a third-party module you do not control pins an incompatible version, upgrade the module itself to a newer release, or fork/replace it. You cannot override another module’s constraint from the root.

5. Update the dependency lock file so it records a version inside the reconciled range, across all platforms you build on:

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

6. Re-run init and confirm resolution succeeds:

terraform init

Installing hashicorp/aws v5.60.0...
Terraform has been successfully initialized!

Prevention

• Use compatible-major constraints like ~> 5.60 consistently and avoid open-ended >= with no upper bound in shared modules.
• Centralize provider version pins in a single versions.tf per module and review them together during upgrades.
• Commit .terraform.lock.hcl and update it deliberately with terraform init -upgrade rather than editing by hand.
• Bump provider versions in one PR across all modules so ranges never drift apart.
• Run terraform init in CI on every change to catch unresolvable constraints before they reach apply.

Related Errors

• Failed to install provider — the version resolved but the download or checksum step failed.
• Invalid version constraint — the constraint string itself is malformed, not merely unsatisfiable.
• provider ... does not have a package available for your platform — resolution succeeded but no build exists for your OS/arch.
• Inconsistent dependency lock file — the lock file no longer matches the constraints and needs -upgrade.

Frequently Asked Questions

Why does adding a module break provider resolution? The new module contributes its own required_providers constraints. Terraform must find one version satisfying the intersection of every module’s range, so a conflicting pin makes the set empty.

Can I override a nested module’s version constraint from the root? No. Each module’s constraints are authoritative for that module. You must update the module (or use a version that satisfies all of them); widening only the root does not help.

How do I fix an unsatisfiable range like >= 5.20.0, < 5.0.0? That constraint can never match. Correct the typo to a coherent range such as >= 5.20.0, < 6.0.0. For prompts that audit and align version pins, see the Terraform prompt library.

Do I need to delete .terraform.lock.hcl? Usually not. Run terraform init -upgrade to let Terraform re-resolve and rewrite the lock. Delete it only as a last resort when it is corrupt.

Where can I find more Terraform version and init fixes? Browse the Terraform guides for related provider, lock file, and initialization troubleshooting.