{"record":{"id":"24394346dc5d123d","repo":"hashicorp/terraform","slug":"failed-to-decode-backend-config-w","errorCode":null,"errorMessage":"failed to decode backend config: %w","messagePattern":"failed to decode backend config: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/workdir/backend_config_state.go","lineNumber":86,"sourceCode":"\treturn nil\n}\n\n// PlanData produces an alternative representation of the receiver that is\n// suitable for storing in a plan. The current workspace must additionally\n// be provided, to be stored alongside the backend configuration.\n//\n// The backend configuration schema is required in order to properly\n// encode the backend-specific configuration settings.\n//\n// As backends are not implemented by providers, the provider schema argument should always be nil\nfunc (s *BackendConfigState) PlanData(schema *configschema.Block, _ *configschema.Block, workspaceName string) (*plans.Backend, error) {\n\tif s == nil {\n\t\treturn nil, nil\n\t}\n\n\tconfigVal, err := s.Config(schema)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to decode backend config: %w\", err)\n\t}\n\treturn plans.NewBackend(s.Type, configVal, schema, workspaceName)\n}\n\nfunc (s *BackendConfigState) DeepCopy() *BackendConfigState {\n\tif s == nil {\n\t\treturn nil\n\t}\n\tret := &BackendConfigState{\n\t\tType: s.Type,\n\t\tHash: s.Hash,\n\t}\n\n\tif s.ConfigRaw != nil {\n\t\tret.ConfigRaw = make([]byte, len(s.ConfigRaw))\n\t\tcopy(ret.ConfigRaw, s.ConfigRaw)\n\t}\n\treturn ret","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/workdir/backend_config_state.go#L68-L104","documentation":"Returned by BackendConfigState.PlanData when s.Config(schema) fails to decode the stored backend config against the provided backend schema while building a plan's Backend block. The %w wraps the underlying decoder error (typically a cty/schema conformance failure on the raw config bytes).","triggerScenarios":"Calling BackendConfigState.PlanData during plan creation when the on-disk backend config (in .terraform/terraform.tfstate) no longer matches the compiled-in backend schema — unknown arguments, wrong types, or a backend type whose schema changed between Terraform versions.","commonSituations":"Downgrading Terraform/OpenTofu after a newer backend wrote config using arguments the older build doesn't know, hand-editing the backend state file, or a backend plugin schema change without `terraform init` re-running.","solutions":["Run `terraform init` against the current binary so the backend config is re-validated and re-written.","Inspect the wrapped error for the offending argument; fix it in the `backend \"<type>\"` block and re-init.","If the binary was downgraded, upgrade back to (or past) the version that wrote the state file.","As a last resort, remove the stale .terraform/terraform.tfstate backend record and re-init from scratch."],"exampleFix":"# before — error on plan after switching terraform versions\nterraform plan\n\n# after — re-initialise so the backend config matches the binary\nterraform init\nterraform plan","handlingStrategy":"validation","validationCode":"// pre-flight before calling PlanData: confirm config decodes against current schema\nif _, err := s.Config(schema); err != nil {\n    return nil, fmt.Errorf(\"re-run `terraform init`: backend config no longer matches schema: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"configVal, err := s.Config(schema)\nif err != nil {\n    return nil, fmt.Errorf(\"failed to decode backend config: %w; run `terraform init` to reconcile\", err)\n}","preventionTips":["Always run `terraform init` after upgrading or downgrading Terraform.","Keep the backend block under version control and review changes.","Don't hand-edit .terraform/terraform.tfstate."],"tags":["backend","config-decode","schema-mismatch","plan"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}