hashicorp/terraform · error

Error loading state: %[2]s Terraform failed to load the

Error message

Error loading state:
    %[2]s

Terraform failed to load the default state from the %[1]q backend.
State migration cannot occur unless the state can be loaded. Backend
modification and state migration has been aborted. The state in both the
source and the destination remain unmodified. Please resolve the
above error and try again.

What it means

Returned by backendMigrateState_s_s (single-to-single) when obtaining the source workspace's StateMgr fails with diagnostics errors — i.e., opts.Source.StateMgr(opts.sourceWorkspace) at line 267 returns HasErrors. The migration cannot proceed because the source state manager (the reader) could not even be constructed, so nothing is read or written.

Source

Thrown at internal/command/meta_backend_migrate.go:269

		return fmt.Errorf("Migration aborted by user.")
	}

	// Copy the default state
	opts.sourceWorkspace = currentWorkspace

	// now switch back to the default env so we can acccess the new backend
	m.SetWorkspace(backend.DefaultStateName)

	return m.backendMigrateState_s_s(opts)
}

// Single state to single state, assumed default state name.
func (m *Meta) backendMigrateState_s_s(opts *backendMigrateOpts) error {
	log.Printf("[INFO] backendMigrateState: single-to-single migrating %q workspace to %q workspace", opts.sourceWorkspace, opts.destinationWorkspace)

	sourceState, sDiags := opts.Source.StateMgr(opts.sourceWorkspace)
	if sDiags.HasErrors() {
		return fmt.Errorf(strings.TrimSpace(
			errMigrateSingleLoadDefault), opts.SourceType, sDiags.Err())
	}
	if err := sourceState.RefreshState(); err != nil {
		return fmt.Errorf(strings.TrimSpace(
			errMigrateSingleLoadDefault), opts.SourceType, err)
	}

	// Do not migrate workspaces without state.
	if sourceState.State().Empty() {
		log.Print("[TRACE] backendMigrateState: source workspace has empty state, so nothing to migrate")
		return nil
	}

	var err error
	destinationState, sDiags := opts.Destination.StateMgr(opts.destinationWorkspace)
	if sDiags.HasErrors() {
		if sDiags.Err().Error() == backend.ErrDefaultWorkspaceNotSupported.Error() {
			// If the backend doesn't support using the default state, we ask the user

View on GitHub (pinned to c9def3e214)

Solutions

1. Inspect the %[2]s inner error for the exact StateMgr construction failure.
2. Verify the source backend block configuration (credentials, endpoint, bucket, path, key).
3. Confirm the current workspace name is valid: run 'terraform workspace list' against the source.
4. Re-authenticate / refresh credentials for the source backend, then re-run 'terraform init'.
5. If the source state file is local, ensure the file exists at the configured path and is readable.

Example fix

// before: source S3 backend StateMgr fails on stale credentials
//   backend "s3" { bucket = "tf-state" ... }  // old creds
// fix: refresh creds and retry
//   aws s3 ls s3://tf-state  # verify access
//   terraform init

# Validate source backend config and StateMgr reachability before init.
# For S3: confirm bucket + key readable with the configured identity.
aws sts get-caller-identity >/dev/null || { echo 'creds invalid'; exit 1; }
aws s3api head-object --bucket "$TF_SRC_BUCKET" --key "$TF_SRC_KEY" >/dev/null 2>&1 \
  || echo 'warn: source key not readable'
# Then run init.
terraform init

# Surface source StateMgr construction failures distinctly.
terraform init 2>/tmp/init.err || rc=$?
if grep -q 'failed to load the default state' /tmp/init.err; then
  echo 'Source StateMgr construction failed — check source backend block + creds' >&2
fi
exit ${rc:-0}

When it happens

Trigger: The source backend's StateMgr factory rejects the workspace name or backend config — e.g., invalid workspace name, backend misconfiguration (bad credentials resolved at StateMgr time), or the backend type doesn't accept the requested workspace. Error is wrapped at line 269 using opts.SourceType and the diagnostics error.

Common situations: Backend block has a typo or stale credentials; source workspace name contains characters the backend rejects; source is an S3/local backend whose configuration references a missing path or bucket; migrating after the source credentials expired.

Related errors

• Error migrating the workspace %q from the previous %q backen
• Failed to set new workspace: %s
• Error copying state from the previous %q backend to the newl
• Can't ask approval for state migration when interactive inpu
• Migrating state from HCP Terraform or Terraform Enterprise t

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