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

During backend state migration, Terraform calls back.Workspaces() on a backend to enumerate available workspaces. If the backend returns diagnostics with errors (and the error is not backend.ErrWorkspacesNotSupported), retrieveWorkspaces wraps the diagnostics into this error. No state data in either source or destination is modified because the inspection phase has not begun copying yet.

Source

Thrown at internal/command/meta_backend_migrate.go:589

				opts.DestinationType, dstWord, destinationPath),
		}
	}

	// Confirm with the user that the copy should occur
	return m.confirm(inputOpts)
}

func retrieveWorkspaces(back backend.Backend, sourceType string) ([]string, bool, error) {
	var singleState bool
	var diags tfdiags.Diagnostics

	workspaces, diags := back.Workspaces()
	if diags.HasErrors() && diags.Err().Error() == backend.ErrWorkspacesNotSupported.Error() {
		singleState = true
		diags = nil
	}
	if diags.HasErrors() {
		return nil, singleState, fmt.Errorf(strings.TrimSpace(
			errMigrateLoadStates), sourceType, diags.Err())
	}
	if diags.HasWarnings() {
		log.Printf("[WARN] retrieveWorkspaces: warning(s) returned when getting workspaces: %s", diags.ErrWithWarnings())
	}

	return workspaces, singleState, diags.Err()
}

func (m *Meta) backendMigrateTFC(opts *backendMigrateOpts) error {
	_, sourceTFC := opts.Source.(*cloud.Cloud)
	cloudBackendDestination, destinationTFC := opts.Destination.(*cloud.Cloud)

	sourceWorkspaces, sourceSingleState, err := retrieveWorkspaces(opts.Source, opts.SourceType)
	if err != nil {
		return err
	}
	// to be used below, not yet implemented

View on GitHub (pinned to d32a084675)

Solutions

1. Verify backend credentials are valid: re-authenticate (e.g., `aws sts get-caller-identity`) or refresh tokens
2. Confirm the backend configuration (bucket, key, region, endpoint URL) matches what exists
3. Test network connectivity to the backend endpoint from the machine running Terraform
4. Run `terraform init -reconfigure` to discard any cached backend state and force a fresh connection
5. Check backend-specific logs or API responses for the underlying diagnostics detail printed in the error

Example fix

# before: stale credentials cause workspace enumeration failure
terraform init
# after: refresh credentials and retry
aws sso login && terraform init

// Validate backend connectivity before running init that triggers migration
// Shell pre-check for S3 backend:
//   aws s3 ls s3://<bucket>/<key-prefix> 2>&1 || echo "BACKEND_UNREACHABLE"
//
// Go-level: call backend.Workspaces() in a dry-run before committing to migration
func checkBackendWorkspaces(back backend.Backend) error {
    _, diags := back.Workspaces()
    if diags.HasErrors() {
        if diags.Err().Error() == backend.ErrWorkspacesNotSupported.Error() {
            return nil // single-state backend, expected
        }
        return fmt.Errorf("backend workspace check failed: %w", diags.Err())
    }
    return nil
}

// Type-assert the backend to check capabilities before migration
func supportsWorkspaces(back backend.Backend) bool {
    _, diags := back.Workspaces()
    return !diags.HasErrors() || diags.Err().Error() == backend.ErrWorkspacesNotSupported.Error()
}

When it happens

Trigger: Calling `terraform init` after changing the backend configuration block, where the source backend's Workspaces() call fails. This occurs when the backend cannot enumerate workspaces due to authentication failure, network inaccessibility, or an internal backend error.

Common situations: Expired or invalid backend credentials (e.g., AWS STS token, HTTP backend auth token), incorrect backend URL or bucket/region, network firewall blocking access to a remote backend, S3 bucket lifecycle or permissions changes, or a backend endpoint that is temporarily unavailable.

Related errors

• Error inspecting states in the %q %s: %s Prior to migra
• Error loading state: %[3]s Terraform failed to load the
• No state file was found! State management commands require
• attribute %q is required
• argument %q is required

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