hashicorp/terraform · error

The workspace name %q is not allowed. The name must contain

Error message

The workspace name %q is not allowed. The name must contain only URL safe
characters, contain no path separators, and not be an empty string.

What it means

Emitted by `terraform workspace select` (workspace_select.go:49-50) when the given name fails `ValidWorkspaceName` (workspace.go:19-24): non-empty and equal to its `url.PathEscape`. Uses the same `EnvInvalidName` constant as `workspace new`. Note `select` validates the name, unlike `delete`.

Source

Thrown at internal/command/arguments/workspace_select.go:50

	cmdFlags.BoolVar(&orCreate, "or-create", false, "create workspace if it does not exist")
	if err := cmdFlags.Parse(args); err != nil {
		diags = diags.Append(tfdiags.Sourceless(
			tfdiags.Error,
			"Failed to parse command-line flags",
			err.Error(),
		))
	}

	// `workspace select` takes only one positional argument: workspace name.
	args = cmdFlags.Args()
	var name string
	if len(args) == 0 {
		diags = diags.Append(errors.New("Expected a single argument: NAME.")) // Recreating pre-existing error from command package
	} else {
		// Obtain and validate name argument.
		name = args[0]
		if !ValidWorkspaceName(name) {
			diags = diags.Append(fmt.Errorf(EnvInvalidName, name))
		}

		// Checking for extra arguments here, not with a len != 1 check above, allows the name to be returned
		args = args[1:]
		if len(args) != 0 {
			diags = diags.Append(errors.New("Expected a single argument: NAME."))
		}
	}

	return &WorkspaceSelect{
		Workspace: Workspace{ViewType: ViewHuman},
		OrCreate:  orCreate,
		Name:      name,
	}, diags
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Supply a workspace name that already passed validation when it was created (letters, digits, `-`, `_`).
2. Sanitize derived names: strip or replace `/`, `\`, spaces, colons before selecting.
3. List existing workspaces with `terraform workspace list` to copy the exact valid name.

Example fix

# before
terraform workspace select "feature/auth"
# The workspace name "feature/auth" is not allowed ...

# after
terraform workspace list   # confirm the exact name
terraform workspace select feature-auth

// Reuse the same check the CLI uses before 'workspace select'.
import "net/url"

func validWorkspaceName(name string) bool {
    return name != "" && name == url.PathEscape(name)
}

// Prefer selecting from the list of existing (already-valid) names:
// terraform workspace list  -> pick an exact entry.

When it happens

Trigger: Calling `terraform workspace select <name>` (with or without `-or-create`) where the name is empty or contains non-URL-safe/path-separator characters.

Common situations: Selecting a workspace derived from a branch name containing `/`; passing an env var that is empty; shell globbing producing an invalid token.

Related errors

• The workspace name %q is not allowed. The name must contain
• Expected a workspace name as an argument, instead got an emp
• Failed to select workspace: input not a valid number
• default workspace not supported You can create a new workspa
• empty state name

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