TerraformPilot

DevOps

Terraform Provider Version Conflict: How to Fix

Fix Terraform provider version conflicts between modules, lock files, and constraint mismatches. Resolve dependency lock errors, upgrade providers safely

LLuca Berton1 min read

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

#

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.

#Terraform#DevOps#Troubleshooting#Providers

Share this article

Related articles