hashicorp/terraform · error

saved backend configuration is invalid: %w

Error message

saved backend configuration is invalid: %w

What it means

Appended as a diagnostic in BackendForLocalPlan() (the classic backend branch) when settings.Config.Decode(schema.ImpliedType()) fails. The plan file stored a serialized backend configuration blob, and it cannot be decoded against the current backend's implied schema. The %w wraps the cty decode error. This means the plan file is internally inconsistent with the backend implementation present.

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 c9def3e214)

Solutions

1. Regenerate the plan with the current Terraform and backend versions: `terraform plan -out=plan.tfplan`, then apply.
2. Ensure the same backend plugin version is installed at apply time as was used at plan time (re-run terraform init).
3. If the plan must be reused, align backend/terraform versions to those that created the plan.
4. Discard suspect plan files that may have been truncated by an interrupted process.

Example fix

# before: applying plan from older terraform version
terraform apply old-plan.tfplan
# saved backend configuration is invalid
# after: re-plan with current version
terraform plan -out=plan.tfplan
terraform apply plan.tfplan

// Reject plan files created by a different terraform/backend version before apply
if planWasCreatedByDifferentVersion(planFile) {
    log.Fatal("regenerate the plan with the current terraform/backend version")
}

When it happens

Trigger: Loading a saved plan whose embedded backend configuration was produced by a different version of the backend (schema changed), or the plan file itself is truncated/corrupted. Decode against the current backend's ConfigSchema().ImpliedType() yields a malformed-value error.

Common situations: Applying a plan created with an older Terraform/backend version after upgrading; a plan file edited or partially written by a crashed process; a backend plugin downgraded between plan and apply; copying a plan file across incompatible backend implementations.

Related errors

• failed to decode action %s: %w
• failed to decode backend config: %w
• failed to decode state_store config: %w
• failed to decode state_store's nested provider config: %w
• can't show a saved cloud plan unless the current root module

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