Terraform: "Invalid resource instance data in state" means state and schema disagree

Not specified by the original author.

TL;DR: State was written by a different provider version or edited by hand, and now the schema does not match. Teaches diagnosing the mismatch and the pull-edit-push recovery. Check what changed: provider version in the lock file vs what wrote the state. terraform state pull | head shows the state's terraform_version and provider versions. Validate with terraform plan afterwards.

The error

Error: Invalid resource instance data in state

aws_instance.web: data in state didn't match the schema ...

What you are seeing

Error: Invalid resource instance data in state

aws_instance.web: data in state didn't match the schema ...

The state file contains attributes the current provider schema does not recognize, or is missing ones it requires. Typical causes: provider upgraded/downgraded between writes, state hand-edited, or state written by a different tool (OpenTofu vs Terraform) with schema differences.

First response

1. Check what changed: provider version in the lock file vs what wrote the state. terraform state pull | head shows the state's terraform_version and provider versions.
2. If a provider upgrade caused it, the provider's upgrade guide usually covers state migration. Upgrading forward through the versions (not skipping majors) lets each version migrate the state.
3. If the state was hand-edited, terraform state pull > backup.json, fix the JSON to match the schema (or restore the backup and redo the edit properly with terraform state mv/rm), then terraform state push the fixed file. Validate with terraform plan afterwards.

Rules for agents

1. Always terraform state pull to a backup before any manual state surgery. State push overwrites; there is no undo without the backup.
2. Never downgrade a provider to "fix" state written by a newer provider. Newer state schemas are not backward compatible; downgrading makes it worse.
3. terraform refresh (or plan with refresh) can sometimes reconcile minor mismatches by re-reading real objects. Try it before surgery.
4. If the state is genuinely corrupt beyond repair, the recovery path is: backup, remove the broken entries (terraform state rm), re-import the real objects. Slow but safe.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Terraform.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

State stores provider schemas per resource; version mismatches surface as invalid instance data errors; state pull/push backs up and restores state. Verified against live docs 2026-09-26. Verified against live docs 2026-09-26.