hashicorp/nomad · error

Missing allocation ID

Error message

Missing allocation ID

What it means

ErrMissingAllocID is a request-validation error returned by client allocation endpoints (Stats, Restart, logs, getAlloc) when the request's AllocID field is empty. The handlers reject the call up front rather than attempting a lookup with a blank ID.

Source

Thrown at nomad/structs/errors.go:65

	errDeploymentTerminalNoRun       = "can't run terminal deployment"
	errDeploymentTerminalNoSetHealth = "can't set health of allocations for a terminal deployment"
	errDeploymentRunningNoUnblock    = "can't unblock running deployment"
)

var (
	ErrNoLeader                   = errors.New(errNoLeader)
	ErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)
	ErrNoRegionPath               = errors.New(errNoRegionPath)
	ErrTokenNotFound              = errors.New(errTokenNotFound)
	ErrTokenExpired               = errors.New(errTokenExpired)
	ErrTokenInvalid               = errors.New(errTokenInvalid)
	ErrPermissionDenied           = errors.New(errPermissionDenied)
	ErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)
	ErrNoNodeConn                 = errors.New(errNoNodeConn)
	ErrUnknownMethod              = errors.New(errUnknownMethod)
	ErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)
	ErrNodeLacksRpc               = errors.New(errNodeLacksRpc)
	ErrMissingAllocID             = errors.New(errMissingAllocID)
	ErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)
	ErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)

	// ErrResultPaginatorCreation is returned by list RPC handlers when the
	// result paginator cannot be built, for example when the server cannot
	// evaluate a requested filter expression. api.ResultPaginatorErrorContent
	// duplicates its message so the CLI can match it without importing structs.
	// Keep the two in sync.
	ErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)

	ErrUnknownNode = errors.New(ErrUnknownNodePrefix)

	ErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)
	ErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)
	ErrDeploymentTerminalNoPause     = errors.New(errDeploymentTerminalNoPause)
	ErrDeploymentTerminalNoPromote   = errors.New(errDeploymentTerminalNoPromote)
	ErrDeploymentTerminalNoResume    = errors.New(errDeploymentTerminalNoResume)
	ErrDeploymentTerminalNoUnblock   = errors.New(errDeploymentTerminalNoUnblock)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Populate req.AllocID with a valid allocation ID before the call.
2. Fetch the allocation first (e.g. via Allocations.List or job status) and use its ID.
3. Add client-side validation that errors early when the ID is empty.
4. Verify you are reading the correct field (Alloc.ID, not Job ID or Node ID).

Example fix

// before
req := &nstructs.AllocSpecificRequest{}
// after
req := &nstructs.AllocSpecificRequest{AllocID: alloc.ID}

if allocID == "" { return errors.New("allocation ID is required") }

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

if err := msgpackrpc.CallWithCodec(codec, "ClientAllocations.Stats", req, &resp); err != nil {
    if strings.Contains(err.Error(), structs.ErrMissingAllocID.Error()) {
        return fmt.Errorf("request rejected: alloc ID missing in %T", req)
    }
    return err
}

When it happens

Trigger: Sending ClientAllocations.Stats, ClientAllocations.Restart, or fs/log RPCs with req.AllocID == ""; constructing the request struct without copying the allocation ID from the job/alloc object; tests that deliberately omit AllocID.

Common situations: Automation that reads the alloc ID from an unset variable or empty API response; copying request structs and dropping the ID field; CLI/API callers passing a placeholder before an allocation was actually placed.

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

• no servers
• missing NodeID
• missing AllocID
• missing allocation ID
• missing AllocID

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