hashicorp/nomad · error

missing AllocID

Error message

missing AllocID

What it means

The Signal RPC validates args.AllocID immediately after ACL checks and metrics setup. When AllocID is the empty string the request cannot identify which allocation's task to signal, so the server returns "missing AllocID" without further processing. It is a precondition check before state-store lookup and client forwarding.

Source

Thrown at nomad/client_alloc_endpoint.go:111

	// the Node registration and the cost is fairly high for adding another hope
	// in the forwarding chain.
	args.QueryOptions.AllowStale = true

	authErr := a.srv.Authenticate(nil, args)

	// Potentially forward to a different region.
	if done, err := a.srv.forward("ClientAllocations.Signal", args, args, reply); done {
		return err
	}
	a.srv.MeasureRPCRate("client_allocations", structs.RateMetricWrite, args)
	if authErr != nil {
		return structs.ErrPermissionDenied
	}
	defer metrics.MeasureSince([]string{"nomad", "client_allocations", "signal"}, time.Now())

	// Verify the arguments.
	if args.AllocID == "" {
		return errors.New("missing AllocID")
	}

	// Find the allocation
	snap, err := a.srv.State().Snapshot()
	if err != nil {
		return err
	}

	alloc, err := getAlloc(snap, args.AllocID)
	if err != nil {
		return err
	}

	// Check namespace alloc-lifecycle permission.
	if aclObj, err := a.srv.ResolveACL(args); err != nil {
		return err
	} else if !aclObj.AllowNsOp(alloc.Namespace, acl.NamespaceCapabilityAllocLifecycle) {
		return structs.ErrPermissionDenied

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set args.AllocID to the allocation's UUID before calling Signal.
2. Look up the allocation ID via the Job Allocations API or alloc list if unknown.
3. Validate AllocID is non-empty in caller code before the RPC.

Example fix

// before
args := structs.AllocSpecificRequest{}
err := client.Signal(args, &structs.GenericResponse{})
// after
args := structs.AllocSpecificRequest{AllocID: alloc.ID}
err := client.Signal(args, &structs.GenericResponse{})

if allocID == "" {
    return fmt.Errorf("signal requires a non-empty AllocID")
}

func hasAllocID(args *structs.AllocSpecificRequest) bool {
    return args != nil && args.AllocID != ""
}

When it happens

Trigger: Calling ClientAllocations.Signal with a structs.AllocSpecificRequest whose AllocID is "".

Common situations: Sending a signal from a script/API where the allocation ID variable was empty; job tooling that captured an empty alloc ID from a failed prior lookup; zero-valued request structs in automation.

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

• missing NodeID
• missing allocation ID
• missing AllocID
• missing NodeID
• Failed to stop allocation: %w

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