hashicorp/terraform · error

error when obtaining provider instance during state store…

Error message

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

What it means

Appended as a diagnostic from `Meta.BackendForLocalPlan` when a state store's configured provider factory returns an error from `factory()` — i.e. instantiating the gRPC provider plugin process fails. This occurs during application of a saved plan whose `state_store` block references a provider (e.g. a custom state backend). The factory was found and the schema check passed, but launching the provider binary failed.

Solutions

1. Run `terraform init` to (re)install the required provider plugin named in the wrapped error.
2. Run `terraform providers` / inspect the plan to see which provider the state store requires.
3. Delete `.terraform/providers/` and re-init if the binary may be corrupt.
4. Confirm Terraform CLI and provider versions are compatible (check the provider's releases/CHANGELOG).
5. Read the wrapped `%w` for the exact launch failure (path not found, handshake error, etc.).

Example fix

# before: provider not installed
terraform apply tfplan
# after
terraform init
terraform apply tfplan
# if corrupt:
rm -rf .terraform/providers && terraform init

// Ensure required providers are installed before applying a plan.
// `terraform providers` shows what the state store needs.
// Then `terraform init` installs them.

// Confirm the factory exists before calling it (the schema check above already guards this).
if factory == nil {
    return errors.New("provider factory missing for state store provider")
}

// Provider launch failures are often resolved by re-init; not safe to retry blindly.
provider, err := factory()
if err != nil {
    // run `terraform init`, then re-attempt BackendForLocalPlan
}

When it happens

Trigger: `factory()` (a `providers.Factory` func) returns an error because the provider plugin binary cannot start — missing executable, wrong version, gRPC handshake failure, plugin process crashed on startup, or a lock-file/timeout issue. This is in the `state_store` initialization path of `BackendForLocalPlan`.

Common situations: Provider plugin not installed (`terraform init` not run or `-lockfile=readonly` skipped a needed provider); provider binary corrupted or incompatible with the Terraform CLI version; provider requires a newer gRPC protocol version; OS/architecture mismatch of the downloaded provider; plugin cache or filesystem permission issue.

Related errors

• action schema not found for action
• Failed to convert provider version to Go version
• Failed to negotiate acceptable chunk size. Expected size >…
• Failed to set state store provider configuration
• identity schema not found for type

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

Appendix: source

Thrown at internal/command/meta_backend.go:404

			})
		}

		factory, exists := factories[*settings.Provider.Source]
		if !exists {
			return nil, diags.Append(&hcl.Diagnostic{
				Severity: hcl.DiagError,
				Summary:  "Provider unavailable",
				Detail: fmt.Sprintf("The provider %s (%q) is required to initialize the %q state store, but the matching provider factory is missing. This is a bug in Terraform and should be reported.",
					settings.Provider.Source.Type,
					settings.Provider.Source,
					settings.Type,
				),
			})
		}

		provider, err := factory()
		if err != nil {
			diags = diags.Append(fmt.Errorf("error when obtaining provider instance during state store initialization: %w", err))
			return nil, diags
		}
		log.Printf("[TRACE] Meta.BackendForLocalPlan: launched instance of provider %s (%q)",
			settings.Provider.Source.Type,
			settings.Provider.Source,
		)

		// We purposefully don't have a deferred call to the provider's Close method here because the calling code needs a
		// running provider instance inside the returned backend.Backend instance.
		// Stopping the provider process is the responsibility of the calling code.

		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)",

View on GitHub (pinned to d32a084675)