Introduction

Terraform resolves one provider version per provider source across the entire dependency graph. A root module can request >= 5.0, while a child module still pins < 5.0, and the whole initialization fails before planning starts. The fix is not to keep rerunning terraform init -upgrade; you need to identify which constraint is impossible and then align the module versions or provider ranges.

Symptoms

  • terraform init fails with a provider version selection error
  • The error references multiple incompatible constraints for the same provider
  • A module upgrade or provider major version bump triggered the problem
  • .terraform.lock.hcl still pins a version outside the newly allowed range

Common Causes

  • The root module and a child module require mutually exclusive provider versions
  • A newly upgraded module still does not support the provider major version used elsewhere
  • The dependency lock file pins an older version and masks which module really needs attention
  • Teams widened the root version range without upgrading dependent modules

Step-by-Step Fix

  1. 1.Inspect which modules require which provider versions
  2. 2.Terraform already knows the dependency graph. Use that output instead of searching blindly through many modules.
bash
terraform providers
  1. 1.Find the exact version constraints in code
  2. 2.Search the root module and any local modules for conflicting required_providers blocks. If the problem comes from a registry module, check the module version currently pinned in your source definition.
bash
rg "required_providers|version\\s*=" -n .
  1. 1.Align to one compatible provider range
  2. 2.Either upgrade the older module to a version that supports the newer provider, or temporarily relax the root module if the ecosystem is not ready for the major bump yet.
hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0, < 6.0"
    }
  }
}
  1. 1.Reinitialize and regenerate the dependency lock file
  2. 2.After the constraints are actually compatible, refresh the working directory and lock file so every environment resolves the same provider version.
bash
terraform init -upgrade
terraform providers lock
terraform plan

Prevention

  • Treat provider major upgrades as dependency graph work, not as a single-line root module edit
  • Review child module support before widening provider constraints
  • Commit .terraform.lock.hcl and update it intentionally during upgrade work
  • Standardize module versions across environments so teams do not debug different provider graphs