hashicorp/terraform · error

error when obtaining provider instance during state store in

Error message

error when obtaining provider instance during state store initialization: %w

What it means

Emitted by InitCommand.initBackend when a state_store configuration block is present AND -backend-config overrides are supplied, requiring Terraform to launch the state-store provider (factory()) to read its schema — and factory() returns an error. The %w wraps the underlying provider-launch failure so it propagates with full context. This path only exists under the experimental pluggable-state-storage feature.

Source

Thrown at internal/command/init.go:207

	var opts *BackendOpts
	switch {
	case root.StateStore != nil:
		// state_store config present
		factory, fDiags := c.Meta.StateStoreProviderFactoryFromConfig(root.StateStore, configLocks)
		diags = diags.Append(fDiags)
		if fDiags.HasErrors() {
			return nil, true, diags
		}

		// If overrides supplied by -backend-config CLI flag, process them
		var configOverride hcl.Body
		if !initArgs.BackendConfig.Empty() {
			// We need to launch an instance of the provider to get the config of the state store for processing any overrides.
			provider, err := factory()
			defer provider.Close() // Stop the child process once we're done with it here.
			if err != nil {
				diags = diags.Append(fmt.Errorf("error when obtaining provider instance during state store initialization: %w", err))
				return nil, true, diags
			}

			resp := provider.GetProviderSchema()

			if len(resp.StateStores) == 0 {
				diags = diags.Append(&hcl.Diagnostic{
					Severity: hcl.DiagError,
					Summary:  "Provider does not support pluggable state storage",
					Detail: fmt.Sprintf("There are no state stores implemented by provider %s (%q)",
						root.StateStore.Provider.Name,
						root.StateStore.ProviderAddr),
					Subject: &root.StateStore.DeclRange,
				})
				return nil, true, diags
			}

			stateStoreSchema, exists := resp.StateStores[root.StateStore.Type]

View on GitHub (pinned to c9def3e214)

Solutions

1. Run `terraform init` first to install the state-store provider before adding -backend-config overrides.
2. Inspect the wrapped error (%w) for the provider's startup failure reason and address it (e.g. fix credentials, reinstall provider).
3. Verify the provider version satisfies required_providers constraints and is compatible with this Terraform version.
4. If using dev_overrides, confirm the local provider binary builds and runs; remove the override to use the registry version as a test.
5. Drop the -backend-config override temporarily to isolate whether the failure is the provider itself or the override processing.

Example fix

# before
$ terraform init -backend-config='token=xxx'   # provider not installed yet
# after
$ terraform init                                # install providers first
$ terraform init -backend-config='token=xxx'    # then apply overrides

// Ensure the state-store provider is installed BEFORE adding -backend-config overrides.
if _, err := os.Stat(filepath.Join(pluginsDir, stateStoreProviderName)); err != nil {
    log.Fatal("install the state-store provider first: terraform init")
}

// Wrap init in a retry that first installs providers without overrides.
for attempt := 0; attempt < 2; attempt++ {
    if attempt == 0 {
        run("terraform", "init") // no -backend-config
    }
    if err := run("terraform", "init", "-backend-config=overrides.tfvars"); err == nil { break }
}

When it happens

Trigger: Using `-enable-pluggable-state-storage-experiment` together with `-backend-config=...` overrides and a state_store block, where the required state-store provider binary cannot be started: missing/incorrect provider version, provider plugin not installed, provider crashes on startup, or the provider factory is misconfigured.

Common situations: State-store provider not yet downloaded (forgot `terraform init` for the provider before adding -backend-config overrides); provider version incompatible with the terraform build; provider binary missing execute permissions; dev-override pointing at a stale/broken provider build; provider fails schema RPC due to bad credentials.

Related errors

• Failed to negotiate acceptable chunk size. Expected size > 0
• Provider installation was canceled by an interrupt signal.
• error when obtaining provider instance during state store in
• Failed to set state store provider configuration: %w
• Failed obtain the in-use version of provider %s (%q) used wi

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