hashicorp/nomad · error

invalid name %q. Must match regex %s

Error message

invalid name %q. Must match regex %s

What it means

This error is produced by Namespace.Validate() in nomad/structs when a Namespace's Name fails the validNamespaceName regex (^[a-zA-Z0-9-]{1,128}$). Nomad namespace names may only contain alphanumerics and hyphens, 1-128 chars. The error is accumulated into a multierror and returned to the caller of namespace create/update APIs.

Source

Thrown at nomad/structs/structs.go:5659

	// is provided only the namespace's default node pool is allowed. This field
	// supports wildcard globbing through the use of `*` for multi-character
	// matching. This field cannot be used with Denied.
	Allowed []string

	// Denied specifies the node pools that are not allowed to be used by jobs
	// in this namespace. This field supports wildcard globbing through the use
	// of `*` for multi-character matching. If specified, any node pool is
	// allowed to be used, except for those that match any of these patterns.
	// This field cannot be used with Allowed.
	Denied []string
}

func (n *Namespace) Validate() error {
	var mErr multierror.Error

	// Validate the name and description
	if !validNamespaceName.MatchString(n.Name) {
		err := fmt.Errorf("invalid name %q. Must match regex %s", n.Name, validNamespaceName)
		mErr.Errors = append(mErr.Errors, err)
	}
	if len(n.Description) > maxNamespaceDescriptionLength {
		err := fmt.Errorf("description longer than %d", maxNamespaceDescriptionLength)
		mErr.Errors = append(mErr.Errors, err)
	}

	err := n.NodePoolConfiguration.Validate()
	switch e := err.(type) {
	case *multierror.Error:
		for _, npErr := range e.Errors {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("invalid node pool configuration: %v", npErr))
		}
	case error:
		mErr.Errors = append(mErr.Errors, fmt.Errorf("invalid node pool configuration: %v", e))
	}

	err = n.VaultConfiguration.Validate()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Rename the namespace to contain only a-z, A-Z, 0-9, and '-' (max 128 chars)
2. Remove surrounding whitespace and illegal characters (e.g. replace '_' with '-')
3. If upgrading from an older Nomad, check that pre-existing names still match the regex before API calls
4. Validate names in your provisioning code before submitting via the Nomad API

Example fix

// before
ns := &structs.Namespace{Name: "prod_eu"}
// after
ns := &structs.Namespace{Name: "prod-eu"}

var validNamespaceName = regexp.MustCompile(`^[a-zA-Z0-9-]{1,128}$`)
if !validNamespaceName.MatchString(name) {
    return fmt.Errorf("namespace name %q invalid: use only alphanumerics and hyphens (1-128 chars)", name)
}

func isValidNamespaceName(name string) bool {
    return regexp.MustCompile(`^[a-zA-Z0-9-]{1,128}$`).MatchString(name)
}

When it happens

Trigger: Calling nomad namespace apply/create (CLI, HTTP /v1/namespaces, or structs.Namespace.Validate directly) with a name containing spaces, underscores, dots, slashes, unicode, or exceeding 128 characters, or an empty name.

Common situations: Terraform/Nomad job files or HCL namespace blocks with names like 'my_team' or 'team.eu'; scripting that derives namespace names from directory names; copying names with trailing whitespace.

Related errors

• volume validation failed: no such namespace %q
• mismatched request namespace in request: %q, %q
• must specify at least one namespace
• Invalid namespace %q: %v
• namespace %q using non-existent quota %q

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/38a279803f357597. Report an issue: GitHub.