{"record":{"id":"b89db125466bbabf","repo":"opentofu/opentofu","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/clistate/cli_state.go","lineNumber":95,"sourceCode":"\nfunc (b *BackendState) SetConfig(val cty.Value, schema *configschema.Block) error {\n\tty := schema.ImpliedType()\n\tbuf, err := ctyjson.Marshal(val, ty)\n\tif err != nil {\n\t\treturn err\n\t}\n\tb.ConfigRaw = buf\n\treturn nil\n}\n\nfunc (b *BackendState) ForPlan(schema *configschema.Block, workspaceName string) (*plans.Backend, error) {\n\tif b == nil {\n\t\treturn nil, nil\n\t}\n\n\tconfigVal, err := b.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(b.Type, configVal, schema, workspaceName)\n}\n\nvar ErrNoState = errors.New(\"no state\")\n\ntype jsonVersionOnly struct {\n\tVersion int `json:\"version\"`\n}\n\n// ReadState reads the CLI state file format written by WriteState.\n// dataDirOverridden should be true when the data directory was explicitly\n// overridden (e.g. via TF_DATA_DIR).\nfunc ReadState(src io.Reader, dataDirOverridden bool) (*CLIState, error) {\n\tif f, ok := src.(*os.File); ok && f == nil {\n\t\treturn nil, ErrNoState\n\t}\n","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/opentofu/opentofu/blob/3561785c48c1ce615e7c50261bd351f26053efa2/internal/command/clistate/cli_state.go#L77-L113","documentation":"Raised by BackendState.ForPlan (internal/command/clistate/cli_state.go:95) when the backend configuration cached in the CLI state file (.terraform/terraform.tfstate) cannot be decoded with ctyjson.Unmarshal against the backend schema's implied type. The cached raw config JSON no longer matches what the current backend schema accepts, so building the plans.Backend value fails.","triggerScenarios":"ForPlan called with a schema whose ImpliedType differs from the type the cached ConfigRaw was marshalled with: running plan after OpenTofu changed the backend's schema between versions, after editing the backend block to a type with different attributes, or against a .terraform directory written by a different tool version.","commonSituations":"Upgrading or downgrading OpenTofu without re-running init; a teammate's .terraform directory committed or copied between checkouts with different backend configs; hand-edited cache files; switching between local and remote backend configs without -reconfigure.","solutions":["Run 'tofu init -reconfigure' to rewrite the backend cache from the current configuration, then retry the plan","If reconfigure is not wanted, remove the stale cache file (.terraform/terraform.tfstate) and run 'tofu init'","Verify the backend block in the configuration has attribute names/types valid for the backend (typos produce unexpected-attribute values)","Align all team/CI environments on one OpenTofu version so the cached schema matches"],"exampleFix":"# before\ntofu plan\n# Error: failed to decode backend config: ...\n\n# after\ntofu init -reconfigure\ntofu plan","handlingStrategy":"fallback","validationCode":"// decode the cached config against the schema BEFORE planning:\nif bs != nil && !bs.Empty() {\n    if _, err := bs.Config(backendSchema); err != nil {\n        // stale/incompatible cache: refresh instead of failing later\n        _ = runInitReconfigure()\n    }\n}","typeGuard":null,"tryCatchPattern":"backend, err := b.ForPlan(schema, ws)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to decode backend config\") {\n        // cache/schema drift: regenerate with 'tofu init -reconfigure', then retry once\n        backend, err = afterReinitForPlan(b, schema, ws)\n    }\n    if err != nil {\n        return err\n    }\n}","preventionTips":["Run 'tofu init -reconfigure' after version upgrades or backend block changes","Never share or commit .terraform directories between differing checkouts","Pin one OpenTofu version across team and CI"],"tags":["backend","state-cache","schema","init","plan"],"backgroundTag":null,"analyzedSha":"3561785c48c1ce615e7c50261bd351f26053efa2","analyzedAt":"2026-08-15T23:27:16.226Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}