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

Inspect the wrapped sDiags.Err() for the precise construction failure.

error loading state

Error message

error loading state: %w

What it means

Thrown early in the context-building path when b.StateMgr(op.Workspace) returns diagnostics with errors. StateMgr constructs the remote state manager (which sets up the workspace + state blob access); failure here means the state manager could not even be initialized, before any state read attempt.

Solutions

Inspect the wrapped sDiags.Err() for the precise construction failure.
Verify token, organization, and workspace/prefix are correct (same checks as the org/workspace errors).
Retry 'terraform init' then the operation - transient construction errors often clear.
Re-run 'terraform login' if the wrapped error indicates auth.

Defensive patterns

Strategy: try-catch

Try / catch

// On StateMgr diagnostics errors, surface the wrapped diagnostics and retry transient ones.
sm, sDiags := b.StateMgr(op.Workspace)
if sDiags.HasErrors() {
    if isTransient(sDiags.Err()) { /* retry after backoff */ }
    return fmt.Errorf("state manager init failed: %w", sDiags.Err())
}

Prevention

Run 'terraform init' to surface state-manager setup issues early.
Verify token/workspace access before running operations that need state.
Retry transient construction errors with backoff.

When it happens

Trigger: b.StateMgr(workspace) returns sDiags with HasErrors(). Caused by the underlying remote state manager failing to resolve the workspace/storage, token issues surfaced during manager construction, or internal state-manager setup errors.

Common situations: Workspace inaccessible at manager-construction time; token lacks state read scope; transient error building the state client; backend misconfiguration exposed during StateMgr init.

Related errors

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

Appendix: source

Thrown at internal/backend/remote/backend_context.go:45

func (b *Remote) LocalRun(ctx context.Context, op *backendrun.Operation) (*backendrun.LocalRun, statemgr.Full, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics
	ret := &backendrun.LocalRun{
		PlanOpts: &terraform.PlanOpts{
			Mode:    op.PlanMode,
			Targets: op.Targets,
		},
	}

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

	// Get the remote workspace name.
	remoteWorkspaceName := b.getRemoteWorkspaceName(op.Workspace)

	// Get the latest state.
	log.Printf("[TRACE] backend/remote: requesting state manager for workspace %q", remoteWorkspaceName)
	stateMgr, sDiags := b.StateMgr(op.Workspace)
	if sDiags.HasErrors() {
		diags = diags.Append(fmt.Errorf("error loading state: %w", sDiags.Err()))
		return nil, nil, diags
	}

	log.Printf("[TRACE] backend/remote: requesting state lock for workspace %q", remoteWorkspaceName)
	if diags := op.StateLocker.Lock(stateMgr, op.Type.String()); diags.HasErrors() {
		return 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 remote workspace locked.
		if diags.HasErrors() {
			diags = diags.Append(op.StateLocker.Unlock())
		}
	}()

	log.Printf("[TRACE] backend/remote: reading remote state for workspace %q", remoteWorkspaceName)
	if err := stateMgr.RefreshState(); err != nil {

View on GitHub (pinned to d32a084675)