highIntermediateSymptom-first#providers#version#required_providers#upgrade

Provider version mismatch — required_providers constraint conflict

Error: resource <type> requires version X.Y.Z but provider only has version A.B.C

Likely source:configurationdeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Error: resource <type> requires version X.Y.Z but provider only has version A.B.C
  • terraform init downloads an incompatible provider version
  • Module upgrade fails with provider constraint conflict

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Required providers block

    grep -A5 'required_providers' *.tf

  • Currently installed provider versions

    terraform version

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • A module requires >=4.0 but root requires ~>3.0
  • terraform init shows 'provider version conflict'

Confirm before fixing

grep -r 'required_providers' --include='*.tf' .
READ

Find all required_providers declarations

Fix

terraform init -upgrade
CHANGE

Re-resolve and upgrade provider versions to satisfy all constraints

Expected: Upgraded provider to the latest compatible version

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
terraform providers
READ

Show all provider constraints and installed versions

2
grep -r 'required_providers' --include='*.tf' .
READ

Find all version constraints in the module tree

3
terraform init -upgrade
CHANGE

Upgrade providers to satisfy all constraints

4
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64
CHANGE

Re-lock providers for the target platforms

Prevention

  • Pin provider versions with ~> constraints in required_providers.
  • Commit .terraform.lock.hcl to version control for reproducible installs.
  • Run terraform init -upgrade in CI when modules are updated.
  • Use terraform providers lock to pin across multiple platforms.

Related runbooks

Same stack, same failure family — worth a skim.

Backend initialization required — run terraform initmedium

Backend initialization required: please run "terraform init"

TerraformFoundation2 causes
Open runbook
Registry unreachable — cannot download provider or modulehigh

Failed to request access to registry.terraform.io

TerraformIntermediate3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.