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

Cross-check every attribute in the nested provider = { ... } block against the target provider's documentation for the exact version Terraform resolved.

hashicorp/terraform · error

failed to decode state_store's nested provider config

Error message

failed to decode state_store's nested provider config: %w

What it means

Raised when Terraform cannot decode the nested provider configuration embedded inside a state_store block while preparing the plan file. The state store delegates storage to a provider (e.g. an HTTP backend, cloud KV store); its config is converted to a hcl2 cty.Value against the provider's schema. If the schema does not match the supplied config (unknown fields, wrong types, missing required args), the decode fails. This is distinct from the outer state_store config decode that immediately precedes it.

Solutions

Cross-check every attribute in the nested provider = { ... } block against the target provider's documentation for the exact version Terraform resolved.
Run terraform providers to confirm which provider source address and version is being used, and align the block to that version's schema.
Ensure the provider plugin is installed and its schema is fetchable (terraform init) so Provider.Config() has a schema to validate against.
Remove or correct any unknown/renamed/required-missing attributes surfaced by the wrapped %w error.

Example fix

// before
state_store {
  provider "http" {
    addres = "https://example.com/state" // typo: should be 'address'
  }
}

// after
state_store {
  provider "http" {
    address = "https://example.com/state"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Before plan/apply, validate the nested provider block against the
// resolved provider's schema using terraform console or terraform validate:
//   $ terraform validate
// Confirm the provider version matches the schema you authored against:
//   $ terraform providers
// In HCL, keep a known-good version constraint so schema drift is caught:
terraform {
  required_providers {
    http = { source = "hashicorp/http", version = "~> 3.4" }
  }
}

Try / catch

// In Go code calling ConfigStateStoreForPlan, treat decode errors as fatal
// config errors (do not retry) and surface the wrapped schema error:
storeCfg, err := workdir.ConfigStateStoreForPlan(s, schema)
if err != nil {
    return fmt.Errorf("state_store config invalid, aborting plan: %w", err)
}

Prevention

Pin provider versions in required_providers so the schema you author against is the one Terraform loads.
Run terraform validate in CI before apply to catch schema mismatches early.
Keep the nested provider block minimal and documented against the exact provider version.

When it happens

Trigger: A state_store block whose nested provider = { ... } sub-block contains attributes the provider schema does not recognize, or whose types are incompatible, or that omits a required argument. Also triggered when the provider's schema cannot be resolved (e.g. provider plugin missing or schema fetch failed) so Provider.Config() errors.

Common situations: Typo'd attribute names in the nested provider block; using attributes from a newer/older provider version than the schema Terraform loaded; pointing state_store at a provider that does not actually implement the state-store interface; leftover config after a provider upgrade renamed fields.

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/999a4ca827597e41. Report an issue: GitHub.

Appendix: source

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

//
// 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))
	}

	return plans.NewStateStore(s.Type, providerVersion, s.Provider.Source, storeConfigVal, storeSchema, providerConfigVal, providerSchema, workspaceName)
}

func (s *StateStoreConfigState) DeepCopy() *StateStoreConfigState {

View on GitHub (pinned to d32a084675)