default workspace not supported You can create a new workspa

Error message

default workspace not supported
You can create a new workspace with the "workspace new" command.

What it means

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'.

Source

Thrown at internal/backend/backend.go:28

import (
	"errors"

	"github.com/zclconf/go-cty/cty"

	"github.com/hashicorp/terraform/internal/configs/configschema"
	"github.com/hashicorp/terraform/internal/states/statemgr"
	"github.com/hashicorp/terraform/internal/tfdiags"
)

// DefaultStateName is the name of the default, initial state that every
// backend must have. This state cannot be deleted.
const DefaultStateName = "default"

var (
	// ErrDefaultWorkspaceNotSupported is returned when an operation does not
	// support using the default workspace, but requires a named workspace to
	// be selected.
	ErrDefaultWorkspaceNotSupported = errors.New("default workspace not supported\n" +
		"You can create a new workspace with the \"workspace new\" command.")

	// ErrWorkspacesNotSupported is an error returned when a caller attempts
	// to perform an operation on a workspace other than "default" for a
	// backend that doesn't support multiple workspaces.
	//
	// The caller can detect this to do special fallback behavior or produce
	// a specific, helpful error message.
	ErrWorkspacesNotSupported = errors.New("workspaces not supported")
)

// InitFn is used to initialize a new backend.
type InitFn func() Backend

// Backend is the minimal interface that must be implemented to enable Terraform.
type Backend interface {
	// ConfigSchema returns a description of the expected configuration
	// structure for the receiving backend.

View on GitHub (pinned to c9def3e214)

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.

Example fix

// before: relies on implicit default workspace
backend.StateMgr(backend.DefaultStateName)

// after: create and use a named workspace
name := "prod"
backend.DeleteWorkspace(name, false) // ensure clean slate if needed
sm, diags := backend.StateMgr(name)

Defensive patterns

Strategy: validation

Validate before calling

// Before selecting a workspace, ensure it is non-default for ops that forbid default.
if workspace == backend.DefaultStateName && opRequiresNamedWorkspace {
    return fmt.Errorf("%w; create one with 'terraform workspace new'", backend.ErrDefaultWorkspaceNotSupported)
}

Try / catch

// Detect the sentinel and surface the helpful hint.
ws, diags := b.Workspaces()
if diags.HasErrors() && errors.Is(diags.Err(), backend.ErrDefaultWorkspaceNotSupported) {
    log.Println("create a workspace: terraform workspace new <name>")
}

Prevention

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).

When it happens

Trigger: 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).

Common situations: 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".

Related errors

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