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 new when the provided workspace name fails the ValidWorkspaceName check. ValidWorkspaceName returns true only if the name is non-empty and equals its own url.PathEscape output, meaning it must contain only URL-safe characters with no path separators. The error message is defined by the EnvInvalidName constant.

Solutions

Use only alphanumeric characters, hyphens, and underscores in workspace names
Remove any path separators (/ or \) from the name
Replace spaces and special characters with hyphens
Ensure the name variable is non-empty

Example fix

# before
terraform workspace new "team/dev-env"

# after
terraform workspace new "team-dev-env"

Defensive patterns

Strategy: validation

Validate before calling

// Mirror Terraform's ValidWorkspaceName before invoking terraform workspace new
func validWorkspaceName(name string) bool {
    if name == "" {
        return false
    }
    return name == url.PathEscape(name)
}

Prevention

Restrict workspace names to alphanumeric characters, hyphens, and underscores
Avoid path separators (/ and \) in workspace names
Validate names in automation before running terraform workspace new
Use url.PathEscape equivalence as the validation rule to match Terraform exactly

When it happens

Trigger: Running terraform workspace new <name> where name contains slashes, backslashes, spaces, special characters, or is empty. ValidWorkspaceName returns false because name != url.PathEscape(name), triggering fmt.Errorf(EnvInvalidName, name).

Common situations: Using names with slashes (e.g., team/workspace); including spaces or special characters (@, :, etc.); using path-like names that resemble directories; empty string from environment variable expansion.

Related errors

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

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