Terraform Provider Version Mismatch Errors After Upgrade

Terraform 0.13+ locks provider versions per module. After upgrades you see 'no available releases match the given constraints' or behavior drift — resolve the lockfile deliberately, never by deleting state.

What you'll see

Root causes

required_providers constraints vs lockfile

version = "~> 3.0" plus a lockfile pinned to 2.x (or vice versa) can't resolve. The lockfile exists so every machine/env uses identical provider builds — commit it, update it explicitly.

Major version schema changes

aws provider v4→v5 changed attribute semantics (e.g. some deprecated fields removed): plan output diffs everywhere. The upgrade guide per provider is required reading, not optional.

Fix it

  1. See what's pinned vs required
    terraform version ; grep -A3 required_providers *.tf ; grep -A5 'provider' .terraform.lock.hcl | head -15
  2. Update the lockfile deliberately
    terraform init -upgrade   # bumps within constraints and rewrites .terraform.lock.hcl
  3. For a major bump: change constraints, read the guide, then re-plan
    # version = "~> 5.0" ; terraform init -upgrade ; terraform plan -out=tfplan   # read every diff before apply
  4. Keep the lockfile committed so CI matches local exactly
    git add .terraform.lock.hcl ; # CI should run terraform init (no -upgrade) — identical provider builds everywhere

Field note

terraform init -upgrade is safe (code/state untouched); terraform apply is where caution lives. Pin major versions in required_providers and let lockfiles handle exact builds: floaty constraints are how teammates end up on different provider behavior.

Common questions

Can I just delete .terraform.lock.hcl when it conflicts?

You can, but you lose reproducibility — every run picks whatever satisfies constraints that day, and provider behavior drift breaks plans. Update the lock (init -upgrade) and commit it instead.

Why did my plan show dozens of changes after a provider upgrade?

Provider majors often change attribute semantics or defaults. That's the documented upgrade path (guides per major): read them, adjust config, review the plan diff-by-diff before applying.

Ship it right the first time

An opinionated VPC module: per-AZ NAT, explicit dependencies, EKS-ready outputs.

Terraform AWS Foundation — $37 →

One-time. Yours to modify. Instant download from the NinjaOps template store.