hashicorp/nomad · error

Parameter for choose must be in form '<number>|<key>'

Error message

Parameter for choose must be in form '<number>|<key>'

What it means

This error is returned by the choose filtering function when its parameter is not in the '<number>|<key>' format. Nomad's 'choose' filter splits the parameter on '|' and requires exactly two parts: an integer count and a key string. Anything else is rejected as malformed.

Source

Thrown at nomad/structs/errors.go:67

	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)
	ErrDeploymentTerminalNoRun       = errors.New(errDeploymentTerminalNoRun)
	ErrDeploymentTerminalNoSetHealth = errors.New(errDeploymentTerminalNoSetHealth)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Change the parameter to '<number>|<key>', e.g. '2|service-name'.
2. Ensure the first token is a valid integer parseable by strconv.Atoi (no spaces or letters).
3. Include the '|' separator and a non-empty key as the second token.
4. Verify the expression is generated/escaped correctly if built programmatically.

Example fix

// before
choose("2 service.web")
// after
choose("2|service.web")

tokens := strings.SplitN(param, "|", 2)
if len(tokens) != 2 {
    return fmt.Errorf("choose parameter must be '<number>|<key>', got %q", param)
}
if _, err := strconv.Atoi(tokens[0]); err != nil {
    return fmt.Errorf("choose count %q is not an integer", tokens[0])
}

When it happens

Trigger: Calling an RPC (e.g. service registration list) with a filter/parameter expression like 'choose' whose argument is missing the '|' separator, has a non-integer first token (e.g. 'abc|key'), or omits one of the two tokens.

Common situations: Hand-written job or query parameters with typos, programmatic string building that leaves the count empty ('|key'), passing a plain number without the key ('2' with no '|key'), or copying expressions across Nomad versions where the syntax changed.

Related errors

• Must provide the NodeID
• failed to create result paginator
• 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/babc9044c9a6bba3. Report an issue: GitHub.