{"record":{"id":"05b4e745fef0de7c","repo":"hashicorp/terraform","slug":"unhandled-backend-configuration-state-this-is-a-b","errorCode":null,"errorMessage":"Unhandled backend configuration state. This is a bug. Please\nreport this error with the following information.\n\nBackend Config Nil: %v\nSaved Backend Empty: %v\nStateStore Config Nil: %v\nSaved StateStore Empty: %v\n","messagePattern":"Unhandled backend configuration state\\. This is a bug\\. Please\nreport this error with the following information\\.\n\nBackend Config Nil: (.+?)\nSaved Backend Empty: (.+?)\nStateStore Config Nil: (.+?)\nSaved StateStore Empty: (.+?)\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/meta_backend.go","lineNumber":1305,"sourceCode":"\n\t\t\treturn savedStateStore, diags\n\t\t}\n\n\t\tinitReason, ssDiags := m.determineStateStoreInitReason(s.StateStore, stateStoreConfig, opts.Locks)\n\t\tdiags = diags.Append(ssDiags)\n\t\tif ssDiags.HasErrors() {\n\t\t\treturn nil, diags\n\t\t}\n\n\t\t// Regardless of whether this code is invoked in an init or non-init command,\n\t\t// we advise users to choose between:\n\t\t// 1. terraform state migrate\n\t\t// 2. terraform init -reconfigure\n\t\tdiags = diags.Append(errStateStoreInitDiag(initReason))\n\t\treturn nil, diags\n\n\tdefault:\n\t\tdiags = diags.Append(fmt.Errorf(\n\t\t\t\"Unhandled backend configuration state. This is a bug. Please\\n\"+\n\t\t\t\t\"report this error with the following information.\\n\\n\"+\n\t\t\t\t\"Backend Config Nil: %v\\n\"+\n\t\t\t\t\"Saved Backend Empty: %v\\n\"+\n\t\t\t\t\"StateStore Config Nil: %v\\n\"+\n\t\t\t\t\"Saved StateStore Empty: %v\\n\",\n\t\t\tbackendConfig == nil,\n\t\t\ts.Backend.Empty(),\n\t\t\tstateStoreConfig == nil,\n\t\t\ts.StateStore.Empty(),\n\t\t))\n\t\treturn nil, diags\n\t}\n}\n\n// determineInitReason is used in non-Init commands to interrupt the command early and prompt users to instead run an init command.\n// That prompt needs to include the reason why init needs to be run, and it is determined here.\n//","sourceCodeStart":1287,"sourceCodeEnd":1323,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/meta_backend.go#L1287-L1323","documentation":"Reached the `default` arm of the backend-configuration state switch inside Meta.backendFromConfig (meta_backend.go:1305). That switch exhaustively enumerates every legal combination of presence/absence for the in-config backend block, the saved backend-state, the in-config state_store block, and the saved state_store-state. Landing in `default` means a combination Terraform considers impossible occurred, so the message itself instructs you to file a bug and prints the four boolean flags (Backend Config Nil, Saved Backend Empty, StateStore Config Nil, Saved StateStore Empty).","triggerScenarios":"Running a command that triggers backendFromConfig after the saved workdir-state file (.terraform/terraform.tfstate) was hand-edited or written by external tooling so it contains a partial mix of backend+state_store fields that no `case` matches; a version downgrade/upgrade that altered the backend-state-file shape; a previous init killed mid-write leaving an internally inconsistent state file.","commonSituations":"A killed/interrupted `terraform init` leaving a half-written .terraform/terraform.tfstate; mixing a `backend` block and a `state_store` block in the same config across versions; third-party tools (terragrunt, custom wrappers) rewriting the workdir state file incorrectly.","solutions":["Run `terraform init -reconfigure` to discard the saved backend/state-store state and reinitialize cleanly from the config alone.","If it reproduces after -reconfigure, capture the four boolean flags printed and file a Terraform bug; do not keep retrying the same command.","Inspect .terraform/terraform.tfstate for hand-edits or corruption and remove/recreate it if a third-party tool mangled it.","Verify you are not simultaneously configuring both a legacy `backend` block and a new `state_store` block in an unsupported way."],"exampleFix":"// before: .terraform/terraform.tfstate manually edited with both backend and state_store partially populated\n// after: rm -rf .terraform && terraform init","handlingStrategy":"validation","validationCode":"// Before commands that init a backend, validate the workdir-state file is sane.\n// Minimal Go check against the same booleans the switch inspects:\nfunc backendConfigStateLooksHandled(s *workdir.BackendStateFile) error {\n    hasBackendCfg := /* backendConfig != nil */\n    savedBackendEmpty := s.Backend.Empty()\n    hasStateStoreCfg := /* stateStoreConfig != nil */\n    savedStateStoreEmpty := s.StateStore.Empty()\n    // Mirror the documented case structure: at most one of backend/state_store\n    // should be active and the saved/unsaved pair should be coherent.\n    if hasBackendCfg && !savedStateStoreEmpty { return fmt.Errorf(\"conflicting backend + saved state_store\") }\n    if hasStateStoreCfg && !savedBackendEmpty { return fmt.Errorf(\"conflicting state_store + saved backend\") }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never hand-edit .terraform/terraform.tfstate; use `terraform init -reconfigure` to reset it.","Avoid configuring both a legacy `backend` block and a `state_store` block in the same configuration.","Commit a clean .terraform.lock.hcl and re-init from scratch on version upgrades.","If a `terraform init` is interrupted, treat the .terraform dir as suspect and reconfigure."],"tags":["backend","init","state","internal-bug","workdir"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}