hashicorp/terraform · error

Error migrating the workspace %q from the previous %q backen

Error message

Error migrating the workspace %q from the previous %q backend
to the newly configured %q backend:
    %s

Terraform copies workspaces in alphabetical order. Any workspaces
alphabetically earlier than this one have been copied. Any workspaces
later than this haven't been modified in the destination. No workspaces
in the source state have been modified.

Please resolve the error above and run the initialization command again.
This will attempt to copy (with permission) all workspaces again.

What it means

Emitted during a multi-state-to-multi-state backend migration when copying a single workspace's state fails. The loop in backendMigrateState_S_S iterates over all source workspaces (sorted alphabetically) and calls backendMigrateState_s_s per workspace; if any one copy errors, it is wrapped with this message. The message communicates partial progress: earlier-named workspaces were copied, later-named ones were not touched, and the source is never modified.

Source

Thrown at internal/command/meta_backend_migrate.go:213

	if wDiags.HasWarnings() {
		log.Printf("[WARN] backendMigrateState_S_S: warning(s) returned when getting workspaces from source backend: %s", wDiags.ErrWithWarnings())
	}

	// Sort the states so they're always copied alphabetically
	sort.Strings(sourceWorkspaces)

	// Go through each and migrate
	for _, name := range sourceWorkspaces {
		// Copy the same names
		opts.sourceWorkspace = name
		opts.destinationWorkspace = name

		// Force it, we confirmed above
		opts.force = true

		// Perform the migration
		if err := m.backendMigrateState_s_s(opts); err != nil {
			return fmt.Errorf(strings.TrimSpace(
				errMigrateMulti), name, opts.SourceType, opts.DestinationType, err)
		}
	}

	return nil
}

// Multi-state to single state.
func (m *Meta) backendMigrateState_S_s(opts *backendMigrateOpts) error {
	log.Printf("[INFO] backendMigrateState: destination backend type %q does not support named workspaces", opts.DestinationType)

	currentWorkspace, err := m.Workspace()
	if err != nil {
		return err
	}

	migrate := opts.force
	if !migrate {

View on GitHub (pinned to c9def3e214)

Solutions

1. Read the inner %s error to identify the failing workspace and root cause (lock, permissions, network).
2. Resolve the per-workspace issue (force-unlock, grant IAM/role access, fix bucket path), then re-run 'terraform init'.
3. Because earlier alphabetical workspaces already copied successfully, re-running init resumes from the same list — Terraform detects equal state with matching lineage and skips already-migrated workspaces.
4. If a destination workspace is corrupted, remove or repair only that destination workspace object before re-running.
5. For lock contention, run 'terraform force-unlock' on the destination workspace lock ID shown in the inner error.

Example fix

// before: destination bucket had a stale lock on workspace 'staging'
//   terraform init  -> Error migrating workspace "staging" ... state lock
// fix:
//   terraform force-unlock <LOCK_ID>   # on destination
//   terraform init                     # resumes; staging copied this time

# Before migrating, verify each destination workspace is writable and unlocked.
for ws in $(terraform workspace list | tr -d '*'); do
  terraform state list -state=<(terraform state pull) >/dev/null 2>&1 && echo "$ws: source readable"
done
# Ensure no stale locks on destination:
# (S3+DynamoDB) aws dynamodb scan --table-name locks --filter-expression "LockID = :id"

# In CI automation around terraform init, retry transient multi-state failures.
init_state() {
  terraform init -input=false -force-copy 2>&1 | tee /tmp/init.log
  rc=${PIPESTATUS[0]}
  if grep -q 'Error migrating the workspace' /tmp/init.log && [ $rc -ne 0 ]; then
    return 1  # signal retry
  fi
  return 0
}
for i in 1 2 3; do init_state && break || sleep $((i*5)); done

When it happens

Trigger: terraform init after changing backend config where BOTH old and new backends support named workspaces (multi-state), and the per-workspace single-to-single migration fails — e.g., destination state lock contention, destination write failure, or a per-workspace StateMgr error. Reached via the case at line 134-141 routing to backendMigrateState_S_S, then the loop at line 203-216.

Common situations: Switching from an S3 backend to a remote/cloud backend (or between remote backends) with multiple workspaces; destination bucket/bucket-key already in use by another state; stale state lock on a destination workspace; insufficient IAM permissions on a subset of workspaces; network blip mid-migration.

Related errors

• Error loading state: %[2]s Terraform failed to load the
• 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/6afd0191fabf11e1. Report an issue: GitHub.