hashicorp/terraform · error

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

Error message

Error inspecting states in the %q backend:
    %s

Prior to changing backends, 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

In Meta.backendMigrateState_S_S (meta_backend_migrate.go:192), after the user agreed to migrate all workspaces, Terraform calls opts.Source.Workspaces() to enumerate the source backend's states. If listing fails, init aborts with this message. The message stresses that neither source nor destination data is modified by the inspection step, so this is safe to retry after fixing the underlying access problem.

Source

Thrown at internal/command/meta_backend_migrate.go:192

				"Do you want to migrate all workspaces to %q?",
				opts.DestinationType),
			Description: fmt.Sprintf(
				strings.TrimSpace(inputBackendMigrateMultiToMulti),
				opts.SourceType, opts.DestinationType),
		})
		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, 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 c9def3e214)

Solutions

1. Read the wrapped error from Source.Workspaces() for the backend-specific cause (AccessDenied, 404, timeout).
2. Verify source-backend credentials and that the principal can LIST states/workspaces (not just read one).
3. Confirm the source backend endpoint/bucket/path still exists and is reachable, then retry init.
4. Reassure: the message confirms source and destination remain unmodified, so retrying is safe once access is fixed.

Example fix

// before: terraform init -migrate-state   (fails: Error inspecting states in the 'remote' backend: AccessDenied)
// after: # grant list on source backend, then retry
terraform init -migrate-state

// Before migrating, confirm the SOURCE backend can enumerate its workspaces.
func sourceCanListWorkspaces(src backend.Backend) error {
    diags := src.Workspaces()
    if diags.HasErrors() { return fmt.Errorf("source backend cannot list workspaces: %w", diags.Err()) }
    return nil
}

// Listing failures are often transient; the inspection step modifies nothing, so retry is safe.
if err := cmd.Init(); err != nil && strings.Contains(err.Error(), "Error inspecting states") {
    time.Sleep(backoff); return cmd.Init()
}

When it happens

Trigger: The SOURCE backend cannot enumerate its workspaces/states due to auth, network, permissions, or a backend-side error (e.g. cannot list S3 keys/DynamoDB entries, cannot reach Consul/HTTP/Azure/GCS); the source credentials are wrong or expired.

Common situations: Expired/temporary credentials for the source backend, insufficient IAM/list permissions, a source bucket/endpoint that no longer exists, or a transient outage during migration.

Related errors

• No state file was found! State management commands require
• error loading state: %w
• sasToken cannot be empty
• unable to build authorizer for Storage API: %+v
• unable to build authorizer for Resource Manager API: %+v

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