schema version %d for %s in state does not match version %d

Error message

schema version %d for %s in state does not match version %d from the provider

What it means

Thrown when the schema version recorded in state for a resource instance does not match the schema version the currently-loaded provider reports for that resource type. Terraform uses schema versions to drive state upgraders; a mismatch means the provider cannot safely decode the stored object.

Source

Thrown at internal/command/jsonstate/state.go:421

			case addrs.DataResourceMode:
				current.Mode = DataResourceMode
			default:
				return ret, fmt.Errorf("resource %s has an unsupported mode %s",
					resAddr.String(),
					resAddr.Mode.String(),
				)
			}

			schema := schemas.ResourceTypeConfig(
				r.ProviderConfig.Provider,
				resAddr.Mode,
				resAddr.Type,
			)

			// It is possible that the only instance is deposed
			if ri.Current != nil {
				if schema.Version != int64(ri.Current.SchemaVersion) {
					return nil, fmt.Errorf("schema version %d for %s in state does not match version %d from the provider", ri.Current.SchemaVersion, resAddr, schema.Version)
				}

				current.SchemaVersion = ri.Current.SchemaVersion

				if schema.Body == nil {
					return nil, fmt.Errorf("no schema found for %s (in provider %s)", resAddr.String(), r.ProviderConfig.Provider)
				}

				// Check if we have an identity in the state
				if ri.Current.IdentityJSON != nil {
					if schema.IdentityVersion != int64(ri.Current.IdentitySchemaVersion) {
						return nil, fmt.Errorf("resource identity schema version %d for %s in state does not match version %d from the provider", ri.Current.IdentitySchemaVersion, resAddr, schema.IdentityVersion)
					}

					if schema.Identity == nil {
						return nil, fmt.Errorf("no resource identity schema found for %s (in provider %s)", resAddr.String(), r.ProviderConfig.Provider)
					}

View on GitHub (pinned to c9def3e214)

Solutions

Match the provider version to what wrote the state: set required_providers to the version that last successfully applied, then `terraform init`.
If upgrading, ensure Terraform runs the resource instance state upgraders by applying with the newer provider rather than just rendering JSON.
If downgrading is intentional, downgrade the provider in lock file and re-init.
For an unrecoverable mismatch, `terraform state rm` the resource, then re-apply/re-import to rewrite state with the current schema.

Example fix

// before: provider downgraded below state schema version
terraform {
  required_providers {
    aws = { source = "hashicorp/aws", version = "= 3.0.0" }
  }
}
// after: restore version that matches state
terraform {
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Before JSON state rendering, verify each resource's state schema version matches the provider.
for _, r := range state.Resources {
    s := schemas.ResourceTypeConfig(r.ProviderConfig.Provider, r.Addr.Mode, r.Addr.Type)
    if r.Current != nil && int64(r.Current.SchemaVersion) != s.Version {
        return fmt.Errorf("schema drift for %s: state=%d provider=%d — re-apply or pin provider", r.Addr, r.Current.SchemaVersion, s.Version)
    }
}

Try / catch

if _, err := jsonstate.MarshalState(state, schemas); err != nil {
    // On schema-version mismatch, re-apply with the matching provider instead of rendering.
    return err
}

Prevention

Keep required_providers versions consistent across environments and over time.
Run `terraform apply` (not just show) after provider upgrades so state upgraders run.
Commit the .terraform.lock.hcl file so provider versions are reproducible.

When it happens

Trigger: Occurs in jsonstate when ri.Current.SchemaVersion != schema.Version (provider's). Triggered by JSON state rendering for a resource whose provider version changed since the state was written (e.g. provider downgraded, or upgraded without running the state upgraders).

Common situations: Most common after a provider downgrade (state was written by provider v2 schema but loaded provider is v1), after restoring an old state file with a newer provider, or when required_providers pins an incompatible version. Also seen with manually edited state files.

Related errors

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/518c4edbb587fb27. Report an issue: GitHub.