hashicorp/nomad · error

evals must be deleted by either ID or filter

Error message

evals must be deleted by either ID or filter

What it means

Guard in Eval.Delete: the request provided neither a list of eval IDs nor a filter expression, so the destructive delete has nothing to act on; exactly one selector must be present.

Source

Thrown at nomad/eval_endpoint.go:478

	// This RPC endpoint is very destructive and alters Nomad's core state,
	// meaning only those with management tokens can call it.
	if aclObj, err := e.srv.ResolveACL(args); err != nil {
		return err
	} else if !aclObj.IsManagement() {
		return structs.ErrPermissionDenied
	}

	if args.Filter != "" && !e.srv.peersCache.ServersMeetMinimumVersion(
		e.srv.Region(), minVersionEvalDeleteByFilter, true) {
		return fmt.Errorf(
			"all servers must be running version %v or later to delete evals by filter",
			minVersionEvalDeleteByFilter)
	}
	if args.Filter != "" && len(args.EvalIDs) > 0 {
		return fmt.Errorf("evals cannot be deleted by both ID and filter")
	}
	if args.Filter == "" && len(args.EvalIDs) == 0 {
		return fmt.Errorf("evals must be deleted by either ID or filter")
	}

	// The eval broker must be disabled otherwise Nomad's state will likely get
	// wild in a very un-fun way.
	if e.srv.evalBroker.Enabled() {
		return errors.New("eval broker is enabled; eval broker must be paused to delete evals")
	}

	if args.Filter != "" {
		count, index, err := e.deleteEvalsByFilter(args)
		if err != nil {
			return err
		}

		// Update the index and return.
		reply.Index = index
		reply.Count = count
		return nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Populate EvalIDs with at least one eval ID or set Filter to a valid expression
2. Check that the eval selection is non-empty before issuing the RPC

Example fix

// before
req := &structs.EvalDeleteRequest{}
// after
if len(ids) > 0 {
    req := &structs.EvalDeleteRequest{EvalIDs: ids}
}

if filter == "" && len(ids) == 0 { return errors.New("eval delete requires IDs or a filter") }

When it happens

Trigger: Sending an EvalDeleteRequest where args.Filter == "" and len(args.EvalIDs) == 0.

Common situations: Empty ID list from upstream code that filtered evals client-side and found none; building the request programmatically without checking that at least one selection criterion is present.

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

• Must provide the NodeID
• Parameter for choose must be in form '<number>|<key>'
• missing node for client registration
• missing node ID for client registration
• missing datacenter for client registration

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