Terraform Module Version Conflict — Fix Guide (2026)

Terraform failing with version constraint conflicts between modules? Here's how to diagnose which module is causing the conflict and resolve it without breaking everything.

Version conflicts in Terraform modules are one of the most frustrating errors — especially in large codebases where multiple modules have overlapping provider requirements.

Common Error Messages

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
4.67.0 does not match configured version constraint >= 5.0.0

Error: Inconsistent dependency lock file

The following dependency selections recorded in the lock file are
inconsistent with the current configuration...

Each Terraform module can declare its own required provider versions. When you call multiple modules that require incompatible versions of the same provider, Terraform can't satisfy all constraints simultaneously.

hcl

# Your root module requires:
terraform {
  required_providers {
    aws = { version = ">= 4.0" }
  }
}
 
# Module A requires:
terraform {
  required_providers {
    aws = { version = ">= 5.0" }  # conflicts if you locked to 4.x
  }
}
 
# Module B requires:
terraform {
  required_providers {
    aws = { version = "~> 4.67"  }  # only allows 4.x
  }
}

Module A and Module B can't both be satisfied at the same time.

Step 1: Find the Conflicting Modules

bash

# Run with detailed logging to see which module has the conflict
TF_LOG=DEBUG terraform init 2>&1 | grep -i "version constraint\|conflict\|required_providers"
 
# Or just init and read the error carefully
terraform init
 
# Show current provider selections
terraform providers
terraform version

The error usually names the module path — look for something like module.vpc or module.eks.

Fix 1: Update Your Lock File

If you upgraded a module but your lock file still has the old provider version:

bash

# Delete the lock file and reinitialize
rm .terraform.lock.hcl
terraform init
 
# Or upgrade specific providers
terraform init -upgrade

-upgrade tells Terraform to ignore the lock file and pick the newest version satisfying all constraints.

Fix 2: Pin Your Root Module to a Compatible Version

Find a provider version that satisfies ALL module constraints:

hcl

# terraform.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0, < 6.0"  # satisfies both ">= 5.0" requirements
    }
  }
}

bash

terraform init -upgrade

Fix 3: Fork and Fix the Conflicting Module

If an external module has an overly restrictive version constraint that's blocking you:

hcl

# Instead of:
module "old_module" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "3.0.0"  # locked to old provider
}
 
# Pin to a newer version of the module that supports newer providers:
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.1.2"  # check registry for latest compatible version
}

Check the module's changelog on the Terraform Registry — version bumps often exist specifically to support newer provider versions.

Fix 4: Use `terraform providers lock` to Reconcile

bash

# Lock providers for specific platforms
terraform providers lock \
  -platform=linux_amd64 \
  -platform=darwin_amd64 \
  -platform=darwin_arm64
 
# This regenerates .terraform.lock.hcl with correct checksums

Fix 5: Check for Transitive Conflicts

The conflict might not be in your direct modules — it could be in a module that a module calls:

bash

# See the full dependency tree
terraform providers
 
# Output looks like:
# ├── provider[registry.terraform.io/hashicorp/aws] >= 4.9.0
# ├── module.vpc
# │   └── provider[registry.terraform.io/hashicorp/aws] >= 5.0.0
# └── module.eks
#     └── provider[registry.terraform.io/hashicorp/aws] ~> 4.67

The conflict is between module.vpc (needs 5.x) and module.eks (needs ~4.67). You need to upgrade module.eks to a version that supports AWS provider 5.x.

Fix 6: Separate State for Incompatible Modules

If modules genuinely can't share the same provider version — split them into separate Terraform roots:

infrastructure/
├── networking/          # uses module that needs aws ~> 4.x
│   ├── main.tf
│   └── terraform.tf
└── kubernetes/          # uses module that needs aws >= 5.0
    ├── main.tf
    └── terraform.tf

Each root has its own .terraform.lock.hcl and can use different provider versions. They share state via terraform_remote_state data sources.

Preventing This in the Future

hcl

# Use flexible version constraints — not overly restrictive
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0"    # good — allows 4.x and 5.x
      # version = "= 4.67.0"  # bad — forces exact version
      # version = "~> 4.67"   # risky — blocks 5.x
    }
  }
}

Commit .terraform.lock.hcl to git. This ensures everyone on the team uses the same provider versions. When you intentionally upgrade, commit the updated lock file.

Quick Checklist

Run terraform providers to see the full dependency tree
Delete .terraform.lock.hcl and run terraform init -upgrade
Update module versions to ones that support newer providers
Use flexible constraints (>=) not exact pins (=) in reusable modules
If genuinely incompatible — split into separate Terraform roots

Terraform Module Version Conflict — Fix Guide (2026)

Common Error Messages

Why This Happens

Step 1: Find the Conflicting Modules

Fix 1: Update Your Lock File

Fix 2: Pin Your Root Module to a Compatible Version

Fix 3: Fork and Fix the Conflicting Module

Fix 4: Use `terraform providers lock` to Reconcile

Fix 5: Check for Transitive Conflicts

Fix 6: Separate State for Incompatible Modules

Preventing This in the Future

Quick Checklist

Stay ahead of the curve

Related Articles

Terraform Plan Succeeds But Apply Fails: How to Fix State Drift and Provider Errors

Terraform Plan Shows Unexpected Destroy — How to Fix It

Terraform .terraform.lock.hcl Conflicts and Provider Version Errors: Fix Guide

Comments