hashicorp/terraform · error

Unhandled backend configuration state. This is a bug. Please

Error message

Unhandled backend configuration state. This is a bug. Please
report this error with the following information.

Backend Config Nil: %v
Saved Backend Empty: %v
StateStore Config Nil: %v
Saved StateStore Empty: %v

What it means

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

Source

Thrown at internal/command/meta_backend.go:1305

			return savedStateStore, diags
		}

		initReason, ssDiags := m.determineStateStoreInitReason(s.StateStore, stateStoreConfig, opts.Locks)
		diags = diags.Append(ssDiags)
		if ssDiags.HasErrors() {
			return nil, diags
		}

		// Regardless of whether this code is invoked in an init or non-init command,
		// we advise users to choose between:
		// 1. terraform state migrate
		// 2. terraform init -reconfigure
		diags = diags.Append(errStateStoreInitDiag(initReason))
		return nil, diags

	default:
		diags = diags.Append(fmt.Errorf(
			"Unhandled backend configuration state. This is a bug. Please\n"+
				"report this error with the following information.\n\n"+
				"Backend Config Nil: %v\n"+
				"Saved Backend Empty: %v\n"+
				"StateStore Config Nil: %v\n"+
				"Saved StateStore Empty: %v\n",
			backendConfig == nil,
			s.Backend.Empty(),
			stateStoreConfig == nil,
			s.StateStore.Empty(),
		))
		return nil, diags
	}
}

// determineInitReason is used in non-Init commands to interrupt the command early and prompt users to instead run an init command.
// That prompt needs to include the reason why init needs to be run, and it is determined here.
//

View on GitHub (pinned to c9def3e214)

Solutions

1. Run `terraform init -reconfigure` to discard the saved backend/state-store state and reinitialize cleanly from the config alone.
2. If it reproduces after -reconfigure, capture the four boolean flags printed and file a Terraform bug; do not keep retrying the same command.
3. Inspect .terraform/terraform.tfstate for hand-edits or corruption and remove/recreate it if a third-party tool mangled it.
4. Verify you are not simultaneously configuring both a legacy `backend` block and a new `state_store` block in an unsupported way.

Example fix

// before: .terraform/terraform.tfstate manually edited with both backend and state_store partially populated
// after: rm -rf .terraform && terraform init

// Before commands that init a backend, validate the workdir-state file is sane.
// Minimal Go check against the same booleans the switch inspects:
func backendConfigStateLooksHandled(s *workdir.BackendStateFile) error {
    hasBackendCfg := /* backendConfig != nil */
    savedBackendEmpty := s.Backend.Empty()
    hasStateStoreCfg := /* stateStoreConfig != nil */
    savedStateStoreEmpty := s.StateStore.Empty()
    // Mirror the documented case structure: at most one of backend/state_store
    // should be active and the saved/unsaved pair should be coherent.
    if hasBackendCfg && !savedStateStoreEmpty { return fmt.Errorf("conflicting backend + saved state_store") }
    if hasStateStoreCfg && !savedBackendEmpty { return fmt.Errorf("conflicting state_store + saved backend") }
    return nil
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to load state: %s
• Error locking state: %s
• Attempted to initialize pluggable state with a nil provider
• Attempted to initialize pluggable state with an empty string
• Can't ask approval for state migration when interactive inpu

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