hashicorp/terraform · error

Error inspecting states in the %q %s: %s Prior to migra

Error message

Error inspecting states in the %q %s:
    %s

Prior to migration, Terraform inspects the source and destination
states to determine what kind of migration steps need to be taken, if any.
Terraform failed to load the states. The data in both the source and the
destination remain unmodified. Please resolve the above error and try again.

What it means

Returned by the multi-state-to-multi-state path when listing workspaces from the source backend fails (`opts.Source.Workspaces()` returns diagnostics with errors). Terraform refuses to proceed because it cannot enumerate what to copy; both backends are left untouched.

Source

Thrown at internal/command/meta_backend_migrate.go:196

				"Do you want to migrate all workspaces to %s %q?",
				dstWord, opts.DestinationType),
			Description: fmt.Sprintf(
				strings.TrimSpace(inputBackendMigrateMultiToMulti),
				opts.SourceType, srcWord, opts.DestinationType, dstWord),
		})
		if err != nil {
			return fmt.Errorf(
				"Error asking for state migration action: %s", err)
		}
	}
	if !migrate {
		return fmt.Errorf("Migration aborted by user.")
	}

	// Read all the states
	sourceWorkspaces, wDiags := opts.Source.Workspaces()
	if wDiags.HasErrors() {
		return fmt.Errorf(strings.TrimSpace(
			errMigrateLoadStates), opts.SourceType, srcWord, wDiags.Err())
	}
	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

View on GitHub (pinned to d32a084675)

Solutions

1. Re-authenticate to the backend (e.g. `aws sso login`, refresh the token, update credentials).
2. Verify network connectivity and the backend endpoint URL/region in the configuration.
3. Check IAM/object-store permissions for list access on the state prefix.
4. Retry `terraform init`; the error message embeds the underlying diagnostic for the specific failure.

# Preflight: can the configured identity list source workspaces?
# Example for S3:
aws s3 ls "s3://${TF_BUCKET}/${TF_KEY_PREFIX}" >/dev/null \
  && echo "source listable" || echo "source list FAILED"
terraform init

# Retry transient backend list failures a bounded number of times:
for i in 1 2 3; do
  terraform init -input=false && break
  if grep -q 'Error inspecting states' /tmp/init.log 2>/dev/null; then
    echo "retry $i after source list failure"; sleep 5; continue
  fi
  exit 1
done

When it happens

Trigger: Fires right after the migration confirmation in `backendMigrateState_S_S` when `opts.Source.Workspaces()` yields a non-empty error diagnostics. Typical root causes: lost credentials, network failure to the remote backend, or a corrupted workspace index.

Common situations: Expired S3/GCS/Azure credentials during init, a remote backend endpoint that is unreachable, IAM permission changes that removed `ListObjects`/equivalent, or a partially-deleted workspace marker object.

Related errors

• Error asking for state migration action: %s
• Migration aborted by user.
• Error migrating the workspace %[1]q from the previous %[2]q
• Error loading state: %[3]s Terraform failed to load the
• Error inspecting states in the %q %s: %s Prior to migra

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