What causes "failed to decode state_store config: %w" in hashicorp/terraform?

Run `terraform init` so ConfigRaw is rewritten against the current schema.

failed to decode state_store config

Error message

failed to decode state_store config: %w

What it means

StateStoreConfigState.PlanData called s.Config(storeSchema) and decoding failed; the %w wraps the cty decoder error. This happens when the raw config bytes in ConfigRaw don't conform to the state_store type's schema while building the plan's StateStore block.

Solutions

Run `terraform init` so ConfigRaw is rewritten against the current schema.
Inspect the wrapped error for the offending argument; fix in the state_store block and re-init.
Upgrade/downgrade to align Terraform and provider versions, then re-init.

Example fix

# before — plan fails decoding state_store config
terraform plan

# after — re-init then plan
terraform init
terraform plan

Defensive patterns

Strategy: validation

Validate before calling

// pre-flight: decode the config separately to give a targeted error
if _, err := s.Config(storeSchema); err != nil {
    return nil, fmt.Errorf("state_store config no longer matches schema; run `terraform init`: %w", err)
}

Try / catch

storeConfigVal, err := s.Config(storeSchema)
if err != nil {
    return nil, fmt.Errorf("failed to decode state_store config: %w; re-run `terraform init`", err)
}

Prevention

Run `terraform init` after provider upgrades.
Pin provider versions in .terraform.lock.hcl.

When it happens

Trigger: Plan-time decoding of the state_store config against the registered schema — unknown arguments, wrong types, or a schema that changed since the file was written (e.g. provider upgrade changed the schema without re-init).

Common situations: Switching provider versions without `terraform init`, schema-breaking provider updates, hand-edited ConfigRaw, or downgrade across a schema-changing release.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at internal/command/workdir/statestore_config_state.go:127

// PlanData produces an alternative representation of the receiver that is
// suitable for storing in a plan. The current workspace must additionally
// be provided, to be stored alongside the state store configuration.
//
// The state_store configuration schema is required in order to properly
// encode the state store-specific configuration settings.
func (s *StateStoreConfigState) PlanData(storeSchema *configschema.Block, providerSchema *configschema.Block, workspaceName string) (*plans.StateStore, error) {
	if s == nil {
		panic("PlanData called on a nil *StateStoreConfigState receiver. This is a bug in Terraform and should be reported.")
	}

	if err := s.Validate(); err != nil {
		return nil, fmt.Errorf("error when preparing state store config for planfile: %s", err)
	}

	storeConfigVal, err := s.Config(storeSchema)
	if err != nil {
		return nil, fmt.Errorf("failed to decode state_store config: %w", err)
	}
	providerConfigVal, err := s.Provider.Config(providerSchema)
	if err != nil {
		return nil, fmt.Errorf("failed to decode state_store's nested provider config: %w", err)
	}

	var providerVersion *version.Version
	switch s.ProviderSupplyMode {
	case getproviders.BuiltIn, getproviders.Reattached, getproviders.DevOverride:
		// For built-in providers, reattached providers, and developer overrides, we don't require version information to be present in the state file, so we should be tolerant of it being missing.
		// In this case we can just use a placeholder version that will never actually be used for anything, but allows us to avoid returning an error when trying to save state store data to a plan file.
		providerVersion = version.Must(version.NewVersion("0.0.0"))
	case getproviders.ManagedByTerraform:
		providerVersion = s.Provider.Version
	default:
		panic(fmt.Sprintf("State store provider %q (%s) has unknown supply mode %q. This is a bug in Terraform and should be reported.", s.Provider.Source.Type, s.Provider.Source.ForDisplay(), s.ProviderSupplyMode))
	}

View on GitHub (pinned to d32a084675)