hashicorp/nomad · warning

Filter expression cannot be used with other filter parameter

Error message

Filter expression cannot be used with other filter parameters

What it means

ErrIncompatibleFiltering is returned by list RPC handlers when a request combines a filter expression with other filter parameters (e.g. prefix, next_token-based legacy filtering). The two filtering mechanisms are mutually exclusive, so the handler rejects the combination instead of producing ambiguous results.

Source

Thrown at nomad/structs/errors.go:66

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove the legacy filter parameters (e.g. Prefix) and keep only the filter expression.
2. Or drop the filter expression and use the other parameters exclusively.
3. In HTTP agents/gateways, ensure only one of filter/prefix is forwarded from the incoming query.
4. Update client code so the query builder emits either filter or legacy params, not both.

Example fix

// before
req := &structs.JobListRequest{QueryOptions: structs.QueryOptions{Prefix: "web", Filter: `Name == "web"`}}
// after
req := &structs.JobListRequest{QueryOptions: structs.QueryOptions{Filter: `Name == "web"`}}

if qo.Filter != "" && (qo.Prefix != "" || qo.NextToken != "") { return errors.New("use either filter expression or legacy filter parameters, not both") }

func filteringIsCompatible(qo structs.QueryOptions) bool { return qo.Filter == "" || (qo.Prefix == "" && qo.NextToken == "") }

if err := apiCall(req); err != nil {
    if strings.HasSuffix(err.Error(), structs.ErrIncompatibleFiltering.Error()) {
        req.QueryOptions.Prefix = "" // keep only the filter expression
        err = apiCall(req)
    }
    return err
}

When it happens

Trigger: Calling a List endpoint with both Filter and another filter parameter (e.g. Prefix) set; API layers forwarding both query parameters simultaneously; pagination plus a filter expression in an incompatible way in Eval.List-style endpoints.

Common situations: HTTP clients adding ?filter=... to a request that already sends prefix or other filter params; older SDK code setting prefix that a newer caller supplements with a filter expression; copy-pasted query builders accumulating parameters.

Related errors

• Missing allocation ID
• Parameter for choose must be in form '<number>|<key>'
• failed to create result paginator
• failed to marshal command into json: %v
• Failed to parse value of %q (%v) as a bool: %v

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