{"record":{"id":"bbaff776a72f5e79","repo":"hashicorp/terraform","slug":"error-inspecting-states-in-the-q-s-s-prio-bbaff7","errorCode":null,"errorMessage":"Error inspecting states in the %q %s:\n    %s\n\nPrior to migration, Terraform inspects the source and destination\nstates to determine what kind of migration steps need to be taken, if any.\nTerraform failed to load the states. The data in both the source and the\ndestination remain unmodified. Please resolve the above error and try again.","messagePattern":"Error inspecting states in the %q (.+?):\n    (.+?)\n\nPrior to migration, Terraform inspects the source and destination\nstates to determine what kind of migration steps need to be taken, if any\\.\nTerraform failed to load the states\\. The data in both the source and the\ndestination remain unmodified\\. Please resolve the above error and try again\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/meta_backend_migrate.go","lineNumber":589,"sourceCode":"\t\t\t\topts.DestinationType, dstWord, destinationPath),\n\t\t}\n\t}\n\n\t// Confirm with the user that the copy should occur\n\treturn m.confirm(inputOpts)\n}\n\nfunc retrieveWorkspaces(back backend.Backend, sourceType string) ([]string, bool, error) {\n\tvar singleState bool\n\tvar diags tfdiags.Diagnostics\n\n\tworkspaces, diags := back.Workspaces()\n\tif diags.HasErrors() && diags.Err().Error() == backend.ErrWorkspacesNotSupported.Error() {\n\t\tsingleState = true\n\t\tdiags = nil\n\t}\n\tif diags.HasErrors() {\n\t\treturn nil, singleState, fmt.Errorf(strings.TrimSpace(\n\t\t\terrMigrateLoadStates), sourceType, diags.Err())\n\t}\n\tif diags.HasWarnings() {\n\t\tlog.Printf(\"[WARN] retrieveWorkspaces: warning(s) returned when getting workspaces: %s\", diags.ErrWithWarnings())\n\t}\n\n\treturn workspaces, singleState, diags.Err()\n}\n\nfunc (m *Meta) backendMigrateTFC(opts *backendMigrateOpts) error {\n\t_, sourceTFC := opts.Source.(*cloud.Cloud)\n\tcloudBackendDestination, destinationTFC := opts.Destination.(*cloud.Cloud)\n\n\tsourceWorkspaces, sourceSingleState, err := retrieveWorkspaces(opts.Source, opts.SourceType)\n\tif err != nil {\n\t\treturn err\n\t}\n\t// to be used below, not yet implemented","sourceCodeStart":571,"sourceCodeEnd":607,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/meta_backend_migrate.go#L571-L607","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify backend credentials are valid: re-authenticate (e.g., `aws sts get-caller-identity`) or refresh tokens","Confirm the backend configuration (bucket, key, region, endpoint URL) matches what exists","Test network connectivity to the backend endpoint from the machine running Terraform","Run `terraform init -reconfigure` to discard any cached backend state and force a fresh connection","Check backend-specific logs or API responses for the underlying diagnostics detail printed in the error"],"exampleFix":"# before: stale credentials cause workspace enumeration failure\nterraform init\n# after: refresh credentials and retry\naws sso login && terraform init","handlingStrategy":"validation","validationCode":"// Validate backend connectivity before running init that triggers migration\n// Shell pre-check for S3 backend:\n//   aws s3 ls s3://<bucket>/<key-prefix> 2>&1 || echo \"BACKEND_UNREACHABLE\"\n//\n// Go-level: call backend.Workspaces() in a dry-run before committing to migration\nfunc checkBackendWorkspaces(back backend.Backend) error {\n    _, diags := back.Workspaces()\n    if diags.HasErrors() {\n        if diags.Err().Error() == backend.ErrWorkspacesNotSupported.Error() {\n            return nil // single-state backend, expected\n        }\n        return fmt.Errorf(\"backend workspace check failed: %w\", diags.Err())\n    }\n    return nil\n}","typeGuard":"// Type-assert the backend to check capabilities before migration\nfunc supportsWorkspaces(back backend.Backend) bool {\n    _, diags := back.Workspaces()\n    return !diags.HasErrors() || diags.Err().Error() == backend.ErrWorkspacesNotSupported.Error()\n}","tryCatchPattern":null,"preventionTips":["Always validate backend credentials and connectivity before running `terraform init` after backend config changes","Use `terraform init -reconfigure` to avoid stale backend cache when switching backends","Run a backend connectivity test (e.g., `aws s3 ls`) before init in CI pipelines","Keep backend configurations fully specified to avoid runtime discovery failures"],"tags":["backend","migration","state","workspaces","configuration"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}