hashicorp/terraform · error

failed to decode state_store config: %w

Error message

failed to decode state_store config: %w

What it means

In PlanData at statestore_config_state.go:125, the stored ConfigRaw JSON is decoded against the state_store schema's implied cty type via ctyjson.Unmarshal. A failure means the stored raw config does not conform to the current schema (an attribute type changed, an unknown/missing block, or corrupt bytes).

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

Solutions

1. Re-run 'terraform init' against the current provider release so ConfigRaw is re-encoded for the current schema.
2. If mid-upgrade, follow the provider's upgrade guide and re-init.
3. Inspect the wrapped cty error for the offending attribute name and type mismatch.

Example fix

// before
$ terraform plan -out=tfplan
Error: failed to decode state_store config: ...attribute "endpoint": string required

// after
$ rm -rf .terraform && terraform init   # re-encodes ConfigRaw for current schema
$ terraform plan -out=tfplan

// Probe-decode ConfigRaw against the schema before PlanData to fail with context.
if _, err := s.Config(storeSchema); err != nil {
    return fmt.Errorf("state_store config will not decode: %w", err)
}

null

if _, err := s.PlanData(storeSchema, provSchema, ws); err != nil {
    if strings.Contains(err.Error(), "failed to decode state_store config") {
        // schema drift; re-init against current provider
    }
}

When it happens

Trigger: s.Config(storeSchema) returns an error from ctyjson.Unmarshal because ConfigRaw doesn't fit storeSchema.ImpliedType().

Common situations: State-store provider schema changed between when the state was written and now; a provider upgrade altered attribute types; corrupt ConfigRaw bytes from a partial write.

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

• failed to decode state_store's nested provider config: %w
• failed to decode action %s: %w
• saved backend configuration is invalid: %w
• error when preparing state store config for planfile: %s
• invalid remote plan format, must be 1

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