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.
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.
Execute terraform init -upgrade to tell Terraform to update module versions to satisfy your new constraints and update the lock file:
terraform init -upgradeThis command will redownload modules that match your updated constraints and regenerate the .terraform.lock.hcl file with compatible versions.
Review the version constraints in your Terraform configuration to ensure they are correct. Check all module blocks for version attributes:
module "example" {
source = "./modules/example"
version = "~> 2.0"
}Ensure the version constraints use valid operators like >=, ~>, <=, and !=.
If terraform init -upgrade doesn't resolve the issue, delete the .terraform directory and reinitialize:
rm -rf .terraform
terraform initThis performs a clean initialization and downloads modules matching your current constraints from scratch.
After running terraform init -upgrade, review the changes to .terraform.lock.hcl:
git diff .terraform.lock.hclCommit the updated lock file to version control to ensure your team uses the same module versions:
git add .terraform.lock.hcl
git commit -m "Update Terraform module lock file"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.
Error: Error rendering template: template not found
How to fix "template not found" error in Terraform
Error: Error generating private key
How to fix 'Error generating private key' in Terraform
Error creating Kubernetes Service: field is immutable
How to fix "field is immutable" errors in Terraform
Error: Error creating local file: open: permission denied
How to fix "Error creating local file: permission denied" in Terraform
Error: line endings have changed from CRLF to LF
Line endings have changed from CRLF to LF in Terraform