hashicorp/terraform · error

workspaces not supported

Error message

workspaces not supported

What it means

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.

Source

Thrown at internal/backend/backend.go:37

// 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.
	//
	// This method does not have any side-effects for the backend and can
	// be safely used before configuring.
	ConfigSchema() *configschema.Block

	// PrepareConfig checks the validity of the values in the given
	// configuration, and inserts any missing defaults, assuming that its
	// structure has already been validated per the schema returned by
	// ConfigSchema.

View on GitHub (pinned to c9def3e214)

Solutions

1. Use only the default workspace with this backend; do not run 'terraform workspace' commands against the http backend.
2. Switch to a backend that supports multiple workspaces (s3, local, gcs, etc.) if you need workspace isolation.
3. In calling code, detect this with errors.Is(err, backend.ErrWorkspacesNotSupported) and skip workspace enumeration or provide a fallback.

Example fix

// before: assumes workspace support
ws, diags := b.Workspaces()

// after: guard against single-workspace backends
ws, diags := b.Workspaces()
if diags.HasErrors() && errors.Is(diags.Err(), backend.ErrWorkspacesNotSupported) {
    ws = []string{backend.DefaultStateName}
}

// Returns true if the backend advertises only a single (default) workspace.
func isSingleWorkspaceBackend(b backend.Backend) bool {
    _, diags := b.Workspaces()
    return diags.HasErrors() && errors.Is(diags.Err(), backend.ErrWorkspacesNotSupported)
}

ws, diags := b.Workspaces()
if diags.HasErrors() {
    if errors.Is(diags.Err(), backend.ErrWorkspacesNotSupported) {
        ws = []string{backend.DefaultStateName} // graceful fallback
    } else {
        return diags // real error
    }
}

When it happens

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

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

Related errors

• default workspace not supported You can create a new workspa
• empty state name
• cannot delete default state
• missing state name
• missing state name

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