hashicorp/terraform · error

error loading state: %w

Error message

error loading state: %w

What it means

In LocalRun(), b.StateMgr(op.Workspace) returned diagnostics containing errors. StateMgr is responsible for reading/creating the workspace and the version check, so this wraps any failure from that stage (e.g. workspace read/create failure or the version-mismatch guard) into a single 'error loading state' diagnostic. The %w preserves the underlying cause for unwrapping.

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 c9def3e214)

Solutions

1. Unwrap the %w error (errors.Unwrap / diags.Err()) to reveal the underlying StateMgr failure and address that directly.
2. Fix the root cause per that underlying error: token/org/name (workspace read), permissions (create), or version alignment.
3. Re-run `terraform init` to re-resolve the backend and re-attempt the StateMgr setup.

Example fix

// before - generic 'error loading state' hides the cause
// after - in Go tooling, unwrap to report specifics:
if err := diags.Err(); err != nil {
  var target error = err
  for errors.Unwrap(target) != nil {
    target = errors.Unwrap(target)
  }
  log.Printf("underlying state load failure: %v", target)
}

func hasStateMgrErrors(d tfdiags.Diagnostics) bool {
    return d.HasErrors()
}

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

When it happens

Trigger: LocalRun() calls StateMgr(); the returned sDiags.HasErrors() is true. The underlying cause is whatever StateMgr returned — typically error 400 (Failed to retrieve workspace), 401 (Error creating workspace), or 402 (version mismatch).

Common situations: Any local-execution operation (`terraform plan`/`apply` when the workspace is in local execution mode or forceLocal) where the workspace can't be read/created or the Terraform version conflicts; the surface message is generic, so unwrap to find the real cause.

Related errors

• error loading state: %w
• default state is not allowed to be deleted
• Failed to lock cos state: %s
• error finding remote workspace: %w
• error loading workspace: %w

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