🚨 OpenTofu Error: 'Unsupported OpenTofu Core version' — Cause, Fix, and Troubleshooting Guide

Overview

The terraform { required_version = ... } block pins which core versions may run a configuration. If the installed tofu binary falls outside that constraint, OpenTofu refuses every command to avoid running against an unsupported engine:

Error: Unsupported OpenTofu Core version

  on versions.tf line 2, in terraform:
   2:   required_version = ">= 1.8.0, < 1.9.0"

This configuration does not support OpenTofu version 1.7.3. To proceed, either
choose another supported OpenTofu version or update this version constraint.
Version constraints are normally set for good reason, so updating the
constraint may lead to other errors or unexpected behavior.

Symptoms

• Every tofu command fails immediately with Unsupported OpenTofu Core version.
• The message names the installed version and the constraint it violates.
• Common in CI where the runner’s tofu version differs from developers’ machines.
• Appears after tightening required_version or upgrading/downgrading the binary.

Common Root Causes

• Binary too old/new for the required_version constraint.
• Drifting CI image — the pipeline pins a different tofu than the team.
• Tightened constraint merged without updating installers.
• Multiple tofu versions on PATH (a version manager selecting the wrong one).
• Migrated Terraform constraint that used a Terraform-version range incompatible with OpenTofu numbering.

How to diagnose

Compare the installed version against the constraint:

tofu version
grep -rn 'required_version' *.tf

Check what is actually on PATH (version managers can surprise you):

which -a tofu
tofu version -json | jq .terraform_version

Fixes

Install a matching version. With tenv (the common OpenTofu/Terraform version manager):

tenv tofu install 1.8.5
tenv tofu use 1.8.5
tofu version

Pin the version in CI so runners match developers:

# GitHub Actions
- uses: opentofu/setup-opentofu@v1
  with:
    tofu_version: 1.8.5

Relax the constraint only if you deliberately support the installed version:

terraform {
  required_version = ">= 1.8.0, < 1.10.0"
}

Verify the environment agrees after the change:

tofu version && tofu validate

What to watch out for

• Constraints exist for a reason — prefer installing the right binary over loosening the range.
• Pin the exact tofu version in CI and in a .opentofu-version/tenv file so everyone matches.
• OpenTofu and Terraform version numbers diverged after the fork — do not assume a Terraform range maps 1:1.
• A version manager may shadow the system binary; which -a tofu reveals the true selection.

Related

• OpenTofu Error: ‘state snapshot was created by a newer version’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Invalid legacy provider address’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Inconsistent dependency lock file’ — Cause, Fix, and Troubleshooting Guide