The workspace name 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

Thrown by terraform workspace select when the workspace name fails ValidWorkspaceName. Identical validation to workspace new: the name must be non-empty and equal to its url.PathEscape output, meaning only URL-safe characters with no path separators.

Solutions

Correct the workspace name to use only URL-safe characters
List available workspaces with terraform workspace list to find the correct name
Remove path separators and special characters from the name

Example fix

# before
terraform workspace select "prod/env"

# after
terraform workspace select "prod-env"

Defensive patterns

Strategy: validation

Validate before calling

// Validate workspace name before terraform workspace select
func validWorkspaceName(name string) bool {
    if name == "" {
        return false
    }
    return name == url.PathEscape(name)
}

Prevention

Check workspace name format before selecting
Use terraform workspace list to verify available names
Avoid path-like separators in workspace names
Validate with url.PathEscape equivalence to match Terraform's rule

When it happens

Trigger: Running terraform workspace select <name> where name contains characters that fail the PathEscape comparison (slashes, spaces, special characters) or is empty. The !ValidWorkspaceName(name) check triggers the error.

Common situations: Selecting a workspace by a path-like name (team/prod); using a name with special characters; empty string from environment variable; typo including a slash character.

Related errors

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

Appendix: 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 d32a084675)