hashicorp/nomad · error

must specify at least one namespace

Error message

must specify at least one namespace

What it means

The namespaces Upsert endpoint requires a non-empty batch. An UpsertNamespaces request with zero namespaces is rejected after management-ACL checks, before per-namespace validation, since there is nothing to write.

Source

Thrown at nomad/namespace_endpoint.go:58

		return err
	}
	n.srv.MeasureRPCRate("namespace", structs.RateMetricWrite, args)
	if authErr != nil {
		return structs.ErrPermissionDenied
	}

	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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure args.Namespaces contains at least one Namespace object before calling the RPC.
2. Skip the API call entirely when the batch is empty on the client side.
3. Check the upstream generation logic (Terraform plan, script loop) for why the list is empty.

Example fix

// before
client.Namespaces().Upsert(&structs.NamespaceUpsertRequest{Namespaces: []*structs.Namespace{}}, nil)
// after
if len(namespaces) == 0 { return nil }
client.Namespaces().Upsert(&structs.NamespaceUpsertRequest{Namespaces: namespaces}, nil)

if len(namespaces) == 0 {
    return nil // nothing to upsert; skip the API call
}

func hasNamespaces(req *structs.NamespaceUpsertRequest) bool {
    return req != nil && len(req.Namespaces) > 0
}

_, err := client.Namespaces().Upsert(req, nil)
if err != nil && strings.Contains(err.Error(), "must specify at least one namespace") {
    log.Printf("empty namespace batch; check upstream plan generation")
}
return err

When it happens

Trigger: Calling the Namespace.Upsert RPC or PUT /v1/namespaces with an empty Namespaces array (e.g. `nomad namespace` tooling, Terraform provider submitting an empty plan, or a script posting `{"Namespaces":[]}`).

Common situations: Infrastructure-as-code plans that evaluate to zero namespace resources and still issue an empty PUT; a JSON template with an empty list; a loop that filters out all namespaces before the request.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• volume validation failed: no such namespace %q
• mismatched request namespace in request: %q, %q
• given no jobs to deregister
• 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/b03567588be0742d. Report an issue: GitHub.