Error: Unsupported Terraform Core version

Fix terraform "Error: Unsupported Terraform Core version"

TL;DR: Your terraform binary is outside the required_version range the configuration demands. Either switch to a matching CLI version with a version manager (tfenv, tenv), or widen the constraint. Note the failing constraint can live in a child module's versions.tf inside .terraform/modules, not in your own files.

The error

Error: Unsupported Terraform Core version

  on versions.tf line 9, in terraform:
   9:   required_version = ">= 1.2"

This configuration does not support Terraform version 1.1.6. To proceed, either choose another supported Terraform version or update this version constraint.

Steps

1. Run terraform version. Expected: you see the binary version the error complains about.
2. Find which constraint rejects it. Check your own versions.tf, then check downloaded modules: grep -rn required_version .terraform/modules/*/versions.tf. Expected: you find the line, possibly inside a module you did not write.
3. Install a matching CLI: tfenv install 1.2.9 && tfenv use 1.2.9 (or tenv). Expected: terraform version now satisfies the constraint.
4. Alternatively, widen the constraint deliberately (for example >= 1.2 to >= 1.1), but only if you understand why it was pinned. Expected: init proceeds; watch for new errors from version-sensitive config.

When this applies

• init or plan fails with "Unsupported Terraform Core version", naming a required_version line and your version.
• A module you depend on requires a newer CLI than you have installed.

When it does NOT apply

• A provider binary complaining about the core version ("provider requires newer Terraform"). That is the provider's requirement, fixed by upgrading the CLI too, but the error text differs.
• Lock-file platform checksum errors. Those are about provider packages, not the CLI version.

Tool and version compatibility

• Terraform CLI 0.12+ through 1.x. required_version is honored by every version; version managers tfenv and tenv cover 0.12 through 1.x.

Why it happens

required_version is a gate the CLI checks before doing anything. Module authors pin it because newer or older cores change language behavior; the gate also applies to constraints inside child modules, so updating your root constraint is not enough when a module demands more.

Edge cases and pitfalls

• An exact pin like required_version = "= 1.15.4" breaks every other version including CI images that ship a newer patch. Prefer ~> 1.15.0 unless you have a reason for the exact pin.
• Terraform Cloud and CI images pin their own CLI version. When the workspace runs 1.1.6 and your config wants >= 1.2, change the workspace's Terraform version setting rather than the code.