Terraform "Unsupported Terraform Core version" in CI

By Kaveh Alemi·Latchkey

A required_version in the terraform {} block pins which CLI versions may run the config. When the runner's Terraform binary falls outside that range, init stops immediately.

What this error means

terraform init fails before touching providers, reporting that the running Terraform version does not meet the configuration's required_version constraint.

Error: Unsupported Terraform Core version

This configuration does not support Terraform version 1.5.7. To proceed,
either choose another supported Terraform version or update the root
module's version constraint (>= 1.8.0).

Common causes

CI pins an older CLI

The runner installs a Terraform version below the required_version floor the config now needs.

Config bumped its constraint

Someone raised required_version for a new feature but the pipeline still installs the old binary.

How to fix it

Pin the matching CLI in CI

Install the Terraform version the configuration requires before init.

# with hashicorp/setup-terraform
- uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: "1.8.5"

Align the constraint deliberately

1. Decide the minimum version the module truly needs.
2. Set required_version to that floor (for example >= 1.8.0).
3. Update every pipeline that runs the module to install a satisfying version.

How to prevent it

• Use a version manager (tfenv) or setup-terraform with an explicit version.
• Keep required_version and the CI-installed version in sync in the same PR.
• Document the supported version range in the module README.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation