hashicorp/terraform · error

saved backend configuration is invalid

Error message

saved backend configuration is invalid: %w

What it means

Appended as a diagnostic from `Meta.BackendForLocalPlan` when decoding the backend configuration saved inside a plan file (`settings.Config.Decode(schema.ImpliedType())`) fails. The plan embedded a serialized backend config blob that does not conform to the backend's current schema's implied type — i.e. the plan is structurally incompatible with the installed backend.

Solutions

1. Recreate the plan with the current Terraform + backend versions: `terraform plan -out=tfplan` then `terraform apply tfplan`.
2. Ensure the same backend type and version are used for both plan and apply.
3. Do not reuse plan files across Terraform CLI upgrades — plans are not forward/backward compatible across schema changes.
4. If the backend config in the repo changed, run `terraform init -reconfigure` before re-planning.

Example fix

# before: applying a stale/incompatible plan
terraform apply old.tfplan
# after: regenerate with current versions
terraform init -reconfigure
terraform plan -out=tfplan
terraform apply tfplan

// Do not reuse plans across backend schema changes.
// Record the Terraform + backend version that created a plan and refuse to apply
// if the current versions differ.
if planVersion != currentVersion {
    return errors.New("plan created with incompatible backend schema; regenerate")
}

null

// Decode failures are not retryable; the plan must be regenerated.
configVal, err := settings.Config.Decode(schema.ImpliedType())
if err != nil {
    return fmt.Errorf("saved backend configuration is invalid: %w; recreate the plan", err)
}

When it happens

Trigger: `settings.Config` (a `hcl2shim`/cty-encoded value stored in the plan) cannot be decoded against the backend's `ConfigSchema().ImpliedType()`. This happens when the plan was created with a different backend schema version, a different backend type, or a corrupted/truncated plan file.

Common situations: Applying a plan created with an older Terraform/backend version on a newer one whose schema changed; applying a plan whose `backend` block type was changed between plan and apply; manually editing or transferring a plan file across incompatible versions; backend plugin upgrade changed its config schema.

Related errors

• action schema not found for action
• Can't serialize backend configuration as JSON
• error determining current workspace when initializing a…
• error in marshalPlanVariables
• identity schema not found for type

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/d1a282c5d5d5ff1e. Report an issue: GitHub.

Appendix: source

Thrown at internal/command/meta_backend.go:547

		// The fully configured Pluggable is used as the instance of backend.Backend
		b = p

	default:
		settings := plan.Backend

		f := backendInit.Backend(settings.Type)
		if f == nil {
			diags = diags.Append(errBackendSavedUnknown{settings.Type})
			return nil, diags
		}
		b = f()
		log.Printf("[TRACE] Meta.BackendForLocalPlan: instantiated backend of type %T", b)

		schema := b.ConfigSchema()
		configVal, err := settings.Config.Decode(schema.ImpliedType())
		if err != nil {
			diags = diags.Append(fmt.Errorf("saved backend configuration is invalid: %w", err))
			return nil, diags
		}

		newVal, validateDiags := b.PrepareConfig(configVal)
		diags = diags.Append(validateDiags)
		if validateDiags.HasErrors() {
			return nil, diags
		}

		configureDiags := b.Configure(newVal)
		diags = diags.Append(configureDiags)
		if configureDiags.HasErrors() {
			return nil, diags
		}
	}

	// If the backend supports CLI initialization, do it.
	if cli, ok := b.(backendrun.CLI); ok {

View on GitHub (pinned to d32a084675)