Quick Answer
# Delete lock file and re-initialize
rm .terraform.lock.hcl
terraform init -upgrade
If that doesn’t work, the conflict is in your version constraints — read on.
The Error
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.40.0 does not match configured version constraint ~> 5.50.
Or:
Error: Incompatible provider version
Provider registry.terraform.io/hashicorp/aws v5.60.0 does not have a
package available for your current platform, linux_arm64.
Or:
Error: Failed to install providers
Could not find compatible versions for provider hashicorp/aws:
root module requires ~> 5.50
module.vpc requires >= 4.0, < 5.0
Cause 1: Lock File Out of Date
The .terraform.lock.hcl file pins exact provider versions. When you update constraints, the lock file conflicts:
# versions.tf — you updated this
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.50" # Raised from ~> 5.40
}
}
# .terraform.lock.hcl — still has 5.40.0 locked
# provider "registry.terraform.io/hashicorp/aws" {
# version = "5.40.0" ← Conflict!
# constraints = "~> 5.40.0"
# }
Fix
terraform init -upgrade
This updates the lock file to the latest version matching your constraints.
Cause 2: Module Version Constraints Conflict
Your root module and a child module require incompatible versions:
# Root module
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.50" # Needs 5.50+
}
}
}
# Child module (from registry)
# Internally requires: version = ">= 4.0, < 5.0" ← Incompatible!
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "4.0.0" # Old module version with old constraint
}
Fix
Update the module to a version compatible with your provider:
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.0" # Supports AWS provider 5.x
}
Then:
terraform init -upgrade
Cause 3: Platform Mismatch
The lock file was generated on a different platform (e.g., macOS) and you’re running on Linux:
Error: Failed to install provider
provider registry.terraform.io/hashicorp/aws: the cached package for
linux_amd64 doesn't match any of the checksums recorded in the lock file
Fix: Generate Hashes for All Platforms
terraform providers lock \
-platform=linux_amd64 \
-platform=linux_arm64 \
-platform=darwin_amd64 \
-platform=darwin_arm64
terraform init
This records checksums for all platforms in .terraform.lock.hcl.
Cause 4: Multiple Providers with Same Source
# ❌ Two different version constraints for the same provider
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.40"
}
}
}
# In another file in the same module:
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "= 5.50.0" # Conflicts with ~> 5.40!
}
}
}
Fix
Keep one required_providers block per provider:
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.50" # Single constraint
}
}
}
Diagnosis Commands
# Show which versions are installed
terraform providers
# Show version constraints from all modules
terraform providers lock -help
# Show the dependency tree
terraform version -json | jq '.provider_selections'
# Check lock file contents
cat .terraform.lock.hcl
Version Constraint Syntax
version = "5.50.0" # Exact version
version = "~> 5.50" # >= 5.50.0, < 6.0.0
version = "~> 5.50.0" # >= 5.50.0, < 5.51.0
version = ">= 5.40" # 5.40.0 or higher
version = ">= 5.40, < 6.0" # Explicit range
Best practice for root modules: Use ~> 5.50 (pessimistic constraint).
Best practice for shared modules: Use >= 5.0 (minimum version, maximum flexibility).
Safe Provider Upgrade Workflow
# 1. Update constraint in versions.tf
# version = "~> 5.60"
# 2. Upgrade
terraform init -upgrade
# 3. Plan — check for breaking changes
terraform plan
# 4. If plan looks good, commit lock file
git add .terraform.lock.hcl versions.tf
git commit -m "upgrade AWS provider to ~> 5.60"
Hands-On Courses
- Terraform for Beginners on CopyPasteLearn
- Terraform By Example — practical code examples
Conclusion
Provider version conflicts usually come from outdated lock files (terraform init -upgrade), incompatible module versions (upgrade the module), or platform mismatches (terraform providers lock for all platforms). Always commit .terraform.lock.hcl to Git and run terraform init -upgrade when changing version constraints.
