{"record":{"id":"36a249e32c021fc5","repo":"hashicorp/terraform","slug":"workspaces-not-supported","errorCode":null,"errorMessage":"workspaces not supported","messagePattern":"workspaces not supported","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/backend.go","lineNumber":37,"sourceCode":"\n// DefaultStateName is the name of the default, initial state that every\n// backend must have. This state cannot be deleted.\nconst DefaultStateName = \"default\"\n\nvar (\n\t// ErrDefaultWorkspaceNotSupported is returned when an operation does not\n\t// support using the default workspace, but requires a named workspace to\n\t// be selected.\n\tErrDefaultWorkspaceNotSupported = errors.New(\"default workspace not supported\\n\" +\n\t\t\"You can create a new workspace with the \\\"workspace new\\\" command.\")\n\n\t// ErrWorkspacesNotSupported is an error returned when a caller attempts\n\t// to perform an operation on a workspace other than \"default\" for a\n\t// backend that doesn't support multiple workspaces.\n\t//\n\t// The caller can detect this to do special fallback behavior or produce\n\t// a specific, helpful error message.\n\tErrWorkspacesNotSupported = errors.New(\"workspaces not supported\")\n)\n\n// InitFn is used to initialize a new backend.\ntype InitFn func() Backend\n\n// Backend is the minimal interface that must be implemented to enable Terraform.\ntype Backend interface {\n\t// ConfigSchema returns a description of the expected configuration\n\t// structure for the receiving backend.\n\t//\n\t// This method does not have any side-effects for the backend and can\n\t// be safely used before configuring.\n\tConfigSchema() *configschema.Block\n\n\t// PrepareConfig checks the validity of the values in the given\n\t// configuration, and inserts any missing defaults, assuming that its\n\t// structure has already been validated per the schema returned by\n\t// ConfigSchema.","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/backend.go#L19-L55","documentation":"ErrWorkspacesNotSupported is returned when a caller attempts a multi-workspace operation (Workspaces, DeleteWorkspace, or StateMgr with a non-default name) on a backend that only supports a single state. The http backend (internal/backend/remote-state/http/backend.go:313,326,330) returns this from StateMgr, Workspaces, and DeleteWorkspace. Callers are expected to detect it (errors.Is) to produce helpful messages or fallback behavior.","triggerScenarios":"Calling Workspaces(), DeleteWorkspace(name, force), or StateMgr(name) where name != \"default\" on the http backend (or any backend embedding this sentinel). Any 'terraform workspace' subcommand against the http backend.","commonSituations":"Using the http remote-state backend and attempting 'terraform workspace list/new/select/delete'; CI scripts that enumerate workspaces generically across all configured backends; code that unconditionally calls Workspaces() without first checking backend capabilities.","solutions":["Use only the default workspace with this backend; do not run 'terraform workspace' commands against the http backend.","Switch to a backend that supports multiple workspaces (s3, local, gcs, etc.) if you need workspace isolation.","In calling code, detect this with errors.Is(err, backend.ErrWorkspacesNotSupported) and skip workspace enumeration or provide a fallback."],"exampleFix":"// before: assumes workspace support\nws, diags := b.Workspaces()\n\n// after: guard against single-workspace backends\nws, diags := b.Workspaces()\nif diags.HasErrors() && errors.Is(diags.Err(), backend.ErrWorkspacesNotSupported) {\n    ws = []string{backend.DefaultStateName}\n}","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"// Returns true if the backend advertises only a single (default) workspace.\nfunc isSingleWorkspaceBackend(b backend.Backend) bool {\n    _, diags := b.Workspaces()\n    return diags.HasErrors() && errors.Is(diags.Err(), backend.ErrWorkspacesNotSupported)\n}","tryCatchPattern":"ws, diags := b.Workspaces()\nif diags.HasErrors() {\n    if errors.Is(diags.Err(), backend.ErrWorkspacesNotSupported) {\n        ws = []string{backend.DefaultStateName} // graceful fallback\n    } else {\n        return diags // real error\n    }\n}","preventionTips":["Do not run 'terraform workspace' subcommands against single-workspace backends like http.","Use errors.Is to detect this sentinel before surfacing raw errors to users.","Document which backends your tooling supports before iterating workspaces."],"tags":["backend","workspace","http-backend","unsupported-operation"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}