hashicorp/nomad · error

must specify at least one namespace to delete

Error message

must specify at least one namespace to delete

What it means

DeleteNamespaces is the RPC handler for deleting Nomad namespaces. Before mutating state it validates the request, and it rejects a request whose Namespaces list is empty because a bulk-delete RPC with no targets is meaningless and almost certainly a client bug. Nothing is deleted when this error is returned.

Source

Thrown at nomad/namespace_endpoint.go:108

	if done, err := n.srv.forward("Namespace.DeleteNamespaces", args, args, reply); done {
		return err
	}
	n.srv.MeasureRPCRate("namespace", structs.RateMetricWrite, args)
	if authErr != nil {
		return structs.ErrPermissionDenied
	}
	defer metrics.MeasureSince([]string{"nomad", "namespace", "delete_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 at least one namespace
	if len(args.Namespaces) == 0 {
		return fmt.Errorf("must specify at least one namespace to delete")
	}

	if slices.Contains(args.Namespaces, structs.DefaultNamespace) {
		return fmt.Errorf("can not delete default namespace")
	}

	// snapshot the state once, because we'll be doing many checks and want
	// consistend state
	snap, err := n.srv.fsm.State().Snapshot()
	if err != nil {
		return err
	}

	var mErr multierror.Error
	for _, ns := range args.Namespaces {
		// make sure this namespace exists before we start making costly checks
		exists, _ := snap.NamespaceByName(nil, ns)
		if exists == nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Pass at least one namespace name in the Namespaces field of the NamespaceDeleteRequest.
2. Check the input list length client-side and skip the RPC if it is empty.
3. If using the CLI, verify namespace names were parsed as arguments (quoting/flag mistakes can yield zero args).

Example fix

// before
client.Namespaces().Delete(&api.NamespaceDeleteRequest{})
// after
if len(names) == 0 { return nil }
client.Namespaces().Delete(&api.NamespaceDeleteRequest{Namespaces: names})

if len(req.Namespaces) == 0 {
    return nil // nothing to delete; skip the RPC
}
_, err := client.Namespaces().Delete(&api.NamespaceDeleteRequest{Namespaces: req.Namespaces})

func hasNamespaces(names []string) bool { return len(names) > 0 }

When it happens

Trigger: Calling the Namespace.Delete RPC (or client.Namespaces().Delete) with an empty Namespaces slice in NamespaceDeleteRequest, e.g. building the request from a filtered list that ended up empty or omitting the field entirely.

Common situations: Automation scripts that filter a namespace list before deleting and end up with zero entries; CLI wrappers that pass no arguments; IaC tools producing empty diff sets.

Related errors

• must provide peer id or address
• can not delete default namespace
• namespace %q has non-terminal jobs in regions: %v
• error parsing: root should be an object
• missing policy name

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