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 new` (workspace_new.go:58-59) when the supplied name fails `ValidWorkspaceName`. That function (workspace.go:19-24) requires the name be non-empty AND equal to its own `url.PathEscape`, i.e. contain only URL-safe characters and no path separators. The message text is the shared `EnvInvalidName` constant.

Source

Thrown at internal/command/arguments/workspace_new.go:59

		diags = diags.Append(tfdiags.Sourceless(
			tfdiags.Error,
			"Failed to parse command-line flags",
			err.Error(),
		))
	}

	// `workspace new` takes only one positional argument: workspace name.
	args = cmdFlags.Args()
	if len(args) != 1 {
		diags = diags.Append(errors.New("Expected a single argument: NAME.")) // Recreating pre-existing error from command package
	}

	// Obtain and validate name argument, but only if there is the expected number of arguments.
	var name string
	if len(args) == 1 {
		name = args[0]
		if !ValidWorkspaceName(name) {
			diags = diags.Append(fmt.Errorf(EnvInvalidName, name))
		}
	}

	return &WorkspaceNew{
		Workspace:   Workspace{ViewType: ViewHuman},
		Name:        name,
		Lock:        stateLock,
		LockTimeout: stateLockTimeout,
		StatePath:   statePath,
	}, diags
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Use only URL-safe, path-separator-free characters (letters, digits, `-`, `_`).
2. Replace separators in derived names, e.g. convert `feature/x` to `feature-x`.
3. Verify with: the name must satisfy `name == url.PathEscape(name)` and `name != ""`.

Example fix

# before
terraform workspace new "feature/login"
# The workspace name "feature/login" is not allowed ...

# after
terraform workspace new "feature-login"

// Mirror internal/command/arguments.ValidWorkspaceName before calling 'workspace new'.
import "net/url"

func validWorkspaceName(name string) bool {
    if name == "" {
        return false
    }
    return name == url.PathEscape(name)
}

func sanitizeWorkspaceName(raw string) (string, error) {
    replacer := strings.NewReplacer("/", "-", "\\", "-", " ", "-")
    name := replacer.Replace(raw)
    if !validWorkspaceName(name) {
        return "", fmt.Errorf("invalid workspace name %q", raw)
    }
    return name, nil
}

When it happens

Trigger: Calling `terraform workspace new <name>` where `<name>` contains spaces, slashes (`/`, `\`), colons, or other characters that change under `url.PathEscape`, or is empty.

Common situations: Naming workspaces after git branch names containing `/` (e.g. `feature/x`); using uppercase or special chars that are not URL-path-safe; passing an empty string.

Related errors

• The workspace name %q is not allowed. The name must contain
• Expected a workspace name as an argument, instead got an emp
• default workspace not supported You can create a new workspa
• empty state name
• missing state name

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