# 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

```text
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.