{"record":{"id":"fe1a2b7f31a7f0ba","repo":"hashicorp/terraform","slug":"default-workspace-not-supported-you-can-create-a-n","errorCode":null,"errorMessage":"default workspace not supported\nYou can create a new workspace with the \"workspace new\" command.","messagePattern":"default workspace not supported\nYou can create a new workspace with the \"workspace new\" command\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/backend.go","lineNumber":28,"sourceCode":"import (\n\t\"errors\"\n\n\t\"github.com/zclconf/go-cty/cty\"\n\n\t\"github.com/hashicorp/terraform/internal/configs/configschema\"\n\t\"github.com/hashicorp/terraform/internal/states/statemgr\"\n\t\"github.com/hashicorp/terraform/internal/tfdiags\"\n)\n\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.","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/backend.go#L10-L46","documentation":"ErrDefaultWorkspaceNotSupported is returned when an operation requires a named workspace but the caller is using the implicit 'default' workspace. The 'default' workspace always exists (backend.DefaultStateName = \"default\") and cannot be deleted, but some backends/operations refuse to operate on it and demand an explicitly-named workspace. The error message itself directs the user to create one via 'terraform workspace new'.","triggerScenarios":"Calling StateMgr(\"default\"), Workspaces, or DeleteWorkspace on a backend whose operations require a non-default workspace (e.g. certain TFE/remote configurations). Selecting the default workspace implicitly (no 'TF_WORKSPACE' env, no 'terraform workspace select') and running a command that calls code paths guarded by errors.Is(..., ErrDefaultWorkspaceNotSupported).","commonSituations":"Running terraform commands without ever creating a named workspace; CI pipelines that assume a default workspace exists but target a backend/operation that forbids it; migrating from local backend to remote where the remote setup rejects the default workspace; tooling that hardcodes workspace=\"default\".","solutions":["Run 'terraform workspace new <name>' (or 'terraform workspace select <name>') to switch off the default workspace before the operation.","If scripting/CI, set the workspace explicitly via the 'TF_WORKSPACE' environment variable or pass the workspace name to the API call rather than relying on the implicit default.","If you genuinely need the default workspace, switch to a backend/operation that supports it instead of one that returns this error."],"exampleFix":"// before: relies on implicit default workspace\nbackend.StateMgr(backend.DefaultStateName)\n\n// after: create and use a named workspace\nname := \"prod\"\nbackend.DeleteWorkspace(name, false) // ensure clean slate if needed\nsm, diags := backend.StateMgr(name)","handlingStrategy":"validation","validationCode":"// Before selecting a workspace, ensure it is non-default for ops that forbid default.\nif workspace == backend.DefaultStateName && opRequiresNamedWorkspace {\n    return fmt.Errorf(\"%w; create one with 'terraform workspace new'\", backend.ErrDefaultWorkspaceNotSupported)\n}","typeGuard":null,"tryCatchPattern":"// Detect the sentinel and surface the helpful hint.\nws, diags := b.Workspaces()\nif diags.HasErrors() && errors.Is(diags.Err(), backend.ErrDefaultWorkspaceNotSupported) {\n    log.Println(\"create a workspace: terraform workspace new <name>\")\n}","preventionTips":["Always create and select a named workspace before operations that require one.","In CI, set TF_WORKSPACE to an explicit non-default name.","Guard generic workspace tooling with errors.Is(err, ErrDefaultWorkspaceNotSupported)."],"tags":["backend","workspace","terraform","configuration"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}