Quick Answer
terraform init -upgrade
The Error
Error: Module version requirements have changed
The previously-installed version "3.19.0" of
registry.terraform.io/terraform-aws-modules/vpc/aws no longer matches
the version constraints "~> 5.0".
Run terraform init -upgrade to install the new version.
What Causes This
- Version constraint changed — someone updated
version = "~> 3.0"toversion = "~> 5.0" - Cached module outdated —
.terraform/modules/has an old version - Module was yanked — the previously installed version was removed from registry
Solution 1: Upgrade Modules
# Re-download modules matching new constraints
terraform init -upgrade
This updates all modules AND providers. To only affect modules:
# Delete module cache and re-init
rm -rf .terraform/modules
terraform init
Solution 2: Version Constraint Syntax
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.0" # >= 5.0.0, < 6.0.0 (recommended)
}
| Constraint | Meaning | Example Range |
|---|---|---|
= 5.1.0 | Exact version | Only 5.1.0 |
>= 5.0 | Minimum version | 5.0+ (any) |
~> 5.0 | Pessimistic (minor) | >= 5.0, < 6.0 |
~> 5.1.0 | Pessimistic (patch) | >= 5.1.0, < 5.2.0 |
>= 5.0, < 5.5 | Range | 5.0 to 5.4.x |
Solution 3: Pin Exact Version in Production
# Development — allow minor updates
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.0"
}
# Production — pin exact version
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "5.8.1" # Exact, predictable
}
Solution 4: Handle Major Version Upgrades
Before upgrading major versions (e.g., 3.x → 5.x):
# 1. Check changelog for breaking changes
# https://github.com/terraform-aws-modules/terraform-aws-vpc/blob/master/CHANGELOG.md
# 2. Plan to see what changes
terraform plan
# 3. Common breaking changes:
# - Renamed variables
# - Removed outputs
# - Changed resource structure (may recreate resources!)
Step-by-Step Major Upgrade
# Step 1: Update version constraint
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.0" # Was "~> 3.0"
}
# Step 2: Re-init
terraform init -upgrade
# Step 3: Plan and review carefully
terraform plan
# ⚠️ Watch for resources being DESTROYED and recreated
# Step 4: Apply in non-prod first
terraform apply
Solution 5: Git Source with Version Tags
For Git-sourced modules:
# Pin to tag
module "vpc" {
source = "git::https://github.com/org/modules.git//vpc?ref=v5.0.0"
}
# Pin to commit (most stable)
module "vpc" {
source = "git::https://github.com/org/modules.git//vpc?ref=abc123f"
}
Hands-On Courses
- Terraform for Beginners on CopyPasteLearn
- Terraform By Example — practical code examples
Conclusion
Run terraform init -upgrade to fetch modules matching updated version constraints. Pin exact versions in production for predictability. Before major version upgrades, check the changelog and plan carefully — major versions may rename variables or restructure resources.