How to fix Error: Module version requirements have changed in Terraform

TerraformBEGINNERMEDIUMUpdated Dec 30, 2025· 102 views

This error occurs when Terraform detects a mismatch between your module version constraints and the currently locked versions. It happens when you update version requirements in your module declarations without updating the .terraform.lock.hcl file.

Quick fix

Fixes Error: Module version requirements have changed

terraform init -upgrade
  1. Run terraform init with the upgrade flag
  2. Verify your module version constraints
  3. Delete and reinitialize if needed
  4. Review and commit the updated lock file
terraform — error
terraform init -upgrade
Error: Module version requirements have changed

What this error means

Terraform maintains a lock file (.terraform.lock.hcl) that tracks the exact versions of modules and providers used in your configuration. When you modify your Terraform configuration to change module version constraints (e.g., updating from `version = "~> 1.0"` to `version = "~> 2.0"`), Terraform detects that the previously locked versions no longer satisfy the new constraints. This mismatch causes Terraform to refuse initialization until the lock file is reconciled with your updated configuration.

Typical symptoms

  • Terraform init fails with 'Module version requirements have changed' error
  • Changes to version constraints in module source declarations trigger the error
  • The .terraform.lock.hcl file contains versions incompatible with updated constraints
  • Error appears when switching between different branches with different module versions

Common causes

  1. You updated module version constraints in your configuration without reinitializing
  2. Version constraints were changed in a shared module or root configuration
  3. The .terraform.lock.hcl file is out of sync with the current configuration
  4. Multiple team members updated version requirements in different ways
  5. Upgrading to a newer version of Terraform with stricter version matching

How to fix "Error: Module version requirements have changed"

1Run terraform init with the upgrade flag

Execute terraform init -upgrade to tell Terraform to update module versions to satisfy your new constraints and update the lock file:

bash
terraform init -upgrade

This command will redownload modules that match your updated constraints and regenerate the .terraform.lock.hcl file with compatible versions.

2Verify your module version constraints

Review the version constraints in your Terraform configuration to ensure they are correct. Check all module blocks for version attributes:

hcl
module "example" {
  source  = "./modules/example"
  version = "~> 2.0"
}

Ensure the version constraints use valid operators like >=, ~>, <=, and !=.

3Delete and reinitialize if needed

If terraform init -upgrade doesn't resolve the issue, delete the .terraform directory and reinitialize:

bash
rm -rf .terraform
terraform init

This performs a clean initialization and downloads modules matching your current constraints from scratch.

4Review and commit the updated lock file

After running terraform init -upgrade, review the changes to .terraform.lock.hcl:

bash
git diff .terraform.lock.hcl

Commit the updated lock file to version control to ensure your team uses the same module versions:

bash
git add .terraform.lock.hcl
git commit -m "Update Terraform module lock file"

Advanced notes

For reusable modules (those intended for use across multiple projects), follow HashiCorp best practices: specify only minimum version constraints (e.g., >= 1.0.0) rather than maximum constraints (e.g., ~> 1.0). This prevents version conflicts in downstream configurations. Root configurations can then manage maximum versions. Additionally, if working in Terraform Cloud, ensure all team members have the same version of Terraform installed, as version mismatches across the team can cause lock file conflicts. When working with CI/CD pipelines, lock the Terraform version in your pipeline configuration (e.g., using terraform version in GitHub Actions) to prevent version drift.

Frequently asked questions

What does "Error: Module version requirements have changed" mean?
hcl) that tracks the exact versions of modules and providers used in your configuration. 0"), Terraform detects that the previously locked versions no longer satisfy the new constraints. This mismatch causes Terraform to refuse initialization until the lock file is reconciled with your updated configuration.
How do I fix "Error: Module version requirements have changed"?
This error occurs when Terraform detects a mismatch between your module version constraints and the currently locked versions. It happens when you update version requirements in your module declarations without updating the .terraform.lock.hcl file.
What causes "Error: Module version requirements have changed"?
You updated module version constraints in your configuration without reinitializing Version constraints were changed in a shared module or root configuration The .terraform.lock.hcl file is out of sync with the current configuration
Is the "Error: Module version requirements have changed" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading