What causes "error loading state: %w" in hashicorp/terraform?

Inspect the wrapped diagnostics error for the specific cause (workspace not found, path error, backend auth failure).

error loading state: %w

Error message

error loading state: %w

What it means

Returned by Local.localRun when b.StateMgr(op.Workspace) returns diagnostics with errors. This is the earliest state-loading failure: the state manager for the requested workspace could not even be constructed/opened before any refresh happens. The wrapped value is the aggregate diagnostics error.

Source

Thrown at internal/backend/local/backend_local.go:53

	// seems bad but we're preserving it for now until we have time to
	// properly design this API, vs. just preserving whatever it currently
	// happens to do.
	op.Type = backendrun.OperationTypeInvalid

	op.StateLocker = op.StateLocker.WithContext(ctx)

	lr, _, stateMgr, diags := b.localRun(ctx, op)
	return lr, stateMgr, diags
}

func (b *Local) localRun(ctx context.Context, op *backendrun.Operation) (*backendrun.LocalRun, *configload.Snapshot, statemgr.Full, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics

	// Get the latest state.
	log.Printf("[TRACE] backend/local: requesting state manager for workspace %q", op.Workspace)
	s, sDiags := b.StateMgr(op.Workspace)
	if sDiags.HasErrors() {
		diags = diags.Append(fmt.Errorf("error loading state: %w", sDiags.Err()))
		return nil, nil, nil, diags
	}
	log.Printf("[TRACE] backend/local: requesting state lock for workspace %q", op.Workspace)
	if diags := op.StateLocker.Lock(s, op.Type.String()); diags.HasErrors() {
		return nil, nil, nil, diags
	}

	defer func() {
		// If we're returning with errors, and thus not producing a valid
		// context, we'll want to avoid leaving the workspace locked.
		if diags.HasErrors() {
			diags = diags.Append(op.StateLocker.Unlock())
		}
	}()

	log.Printf("[TRACE] backend/local: reading remote state for workspace %q", op.Workspace)
	if err := s.RefreshState(); err != nil {
		diags = diags.Append(fmt.Errorf("error loading state: %w", err))

View on GitHub (pinned to c9def3e214)

Solutions

Inspect the wrapped diagnostics error for the specific cause (workspace not found, path error, backend auth failure).
Verify the workspace exists with terraform workspace list; create it with terraform workspace new if missing.
Check the backend configuration and credentials if a delegated backend is involved.

Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure the workspace exists before the operation.
ws, diags := b.Workspaces()
if diags.HasErrors() { return diags }
if !contains(ws, op.Workspace) { return fmt.Errorf("workspace %q not found", op.Workspace) }

Try / catch

s, sDiags := b.StateMgr(op.Workspace)
if sDiags.HasErrors() {
    return fmt.Errorf("error loading state: %w", sDiags.Err())
}

Prevention

Pre-create workspaces with terraform workspace new before referencing them.
Validate backend config and credentials before running operations.
Run terraform workspace list in CI to confirm the target workspace exists.

When it happens

Trigger: StateMgr fails to set up the state file manager for the workspace — e.g. the backend's StateMgr returns an error because the state path is invalid, the workspace doesn't exist, or a delegated backend (b.Backend.StateMgr) errored.

Common situations: Referencing a workspace that doesn't exist for a backend that requires it; corrupt or inaccessible local state path; misconfigured delegated backend (e.g. remote/cloud) that fails to resolve the workspace.

Related errors

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