hashicorp/nomad · error

Invalid namespace %q: %v

Error message

Invalid namespace %q: %v

What it means

Each namespace in an UpsertNamespaces batch is validated with ns.Validate() before the Raft write; on the first invalid namespace the endpoint aborts with this wrapped error naming the namespace and the underlying validation reason (e.g. bad name characters, missing fields).

Source

Thrown at nomad/namespace_endpoint.go:64

	defer metrics.MeasureSince([]string{"nomad", "namespace", "upsert_namespaces"}, time.Now())

	// Check management permissions
	if aclObj, err := n.srv.ResolveACL(args); err != nil {
		return err
	} else if !aclObj.IsManagement() {
		return structs.ErrPermissionDenied
	}

	// Validate there is at least one namespace
	if len(args.Namespaces) == 0 {
		return fmt.Errorf("must specify at least one namespace")
	}

	// Validate the namespaces and set the hash
	for _, ns := range args.Namespaces {
		if err := ns.Validate(); err != nil {
			return fmt.Errorf("Invalid namespace %q: %v", ns.Name, err)
		}

		ns.SetHash()
	}

	// Update via Raft
	_, index, err := n.srv.raftApply(structs.NamespaceUpsertRequestType, args)
	if err != nil {
		return err
	}

	// Update the index
	reply.Index = index
	return nil
}

// DeleteNamespaces is used to delete a namespace
func (n *Namespace) DeleteNamespaces(args *structs.NamespaceDeleteRequest, reply *structs.GenericResponse) error {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %v detail to see which field failed validation and correct that field on the named namespace.
2. Use a valid name: lowercase alphanumeric with hyphens/underscores, non-empty, within length limits.
3. Call ns.Validate() client-side before submitting the batch to catch failures early.
4. Check generated names from automation (branch/label interpolation) for illegal characters.

Example fix

// before
ns := &structs.Namespace{Name: "Prod Team!", Description: "..."}
// after
ns := &structs.Namespace{Name: "prod-team", Description: "..."}
if err := ns.Validate(); err != nil { return err }

for _, ns := range namespaces {
    if err := ns.Validate(); err != nil {
        return fmt.Errorf("namespace %q invalid: %w", ns.Name, err)
    }
}

func validNamespaceName(name string) bool {
    if name == "" || len(name) > 128 { return false }
    for _, r := range name {
        if !(r == '-' || r == '_' || r >= 'a' && r <= 'z' || r >= '0' && r <= '9') { return false }
    }
    return true
}

_, err := client.Namespaces().Upsert(req, nil)
if err != nil {
    var nsName, reason string
    if _, scanErr := fmt.Sscanf(err.Error(), "Invalid namespace %q: %v", &nsName, &reason); scanErr == nil {
        return fmt.Errorf("fix namespace %s: %s", nsName, reason)
    }
}
return err

When it happens

Trigger: Upserting one or more namespaces whose Validate() fails — invalid Name (empty, illegal characters), invalid quota, hash/fields rejected by the namespace schema.

Common situations: Names containing uppercase or special characters not allowed by Nomad namespace naming rules; a namespace struct built with an unset Name; quota references pointing at nonexistent quotas; IaC interpolating malformed names from branch names or labels.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

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