{"record":{"id":"3c652b238f0e73c2","repo":"hashicorp/nomad","slug":"filter-expression-cannot-be-used-with-other-filter","errorCode":null,"errorMessage":"Filter expression cannot be used with other filter parameters","messagePattern":"Filter expression cannot be used with other filter parameters","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"nomad/structs/errors.go","lineNumber":66,"sourceCode":"\terrDeploymentTerminalNoSetHealth = \"can't set health of allocations for a terminal deployment\"\n\terrDeploymentRunningNoUnblock    = \"can't unblock running deployment\"\n)\n\nvar (\n\tErrNoLeader                   = errors.New(errNoLeader)\n\tErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)\n\tErrNoRegionPath               = errors.New(errNoRegionPath)\n\tErrTokenNotFound              = errors.New(errTokenNotFound)\n\tErrTokenExpired               = errors.New(errTokenExpired)\n\tErrTokenInvalid               = errors.New(errTokenInvalid)\n\tErrPermissionDenied           = errors.New(errPermissionDenied)\n\tErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)\n\tErrNoNodeConn                 = errors.New(errNoNodeConn)\n\tErrUnknownMethod              = errors.New(errUnknownMethod)\n\tErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)\n\tErrNodeLacksRpc               = errors.New(errNodeLacksRpc)\n\tErrMissingAllocID             = errors.New(errMissingAllocID)\n\tErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)\n\tErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)\n\n\t// ErrResultPaginatorCreation is returned by list RPC handlers when the\n\t// result paginator cannot be built, for example when the server cannot\n\t// evaluate a requested filter expression. api.ResultPaginatorErrorContent\n\t// duplicates its message so the CLI can match it without importing structs.\n\t// Keep the two in sync.\n\tErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)\n\n\tErrUnknownNode = errors.New(ErrUnknownNodePrefix)\n\n\tErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)\n\tErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)\n\tErrDeploymentTerminalNoPause     = errors.New(errDeploymentTerminalNoPause)\n\tErrDeploymentTerminalNoPromote   = errors.New(errDeploymentTerminalNoPromote)\n\tErrDeploymentTerminalNoResume    = errors.New(errDeploymentTerminalNoResume)\n\tErrDeploymentTerminalNoUnblock   = errors.New(errDeploymentTerminalNoUnblock)\n\tErrDeploymentTerminalNoRun       = errors.New(errDeploymentTerminalNoRun)","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L48-L84","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the legacy filter parameters (e.g. Prefix) and keep only the filter expression.","Or drop the filter expression and use the other parameters exclusively.","In HTTP agents/gateways, ensure only one of filter/prefix is forwarded from the incoming query.","Update client code so the query builder emits either filter or legacy params, not both."],"exampleFix":"// before\nreq := &structs.JobListRequest{QueryOptions: structs.QueryOptions{Prefix: \"web\", Filter: `Name == \"web\"`}}\n// after\nreq := &structs.JobListRequest{QueryOptions: structs.QueryOptions{Filter: `Name == \"web\"`}}","handlingStrategy":"validation","validationCode":"if qo.Filter != \"\" && (qo.Prefix != \"\" || qo.NextToken != \"\") { return errors.New(\"use either filter expression or legacy filter parameters, not both\") }","typeGuard":"func filteringIsCompatible(qo structs.QueryOptions) bool { return qo.Filter == \"\" || (qo.Prefix == \"\" && qo.NextToken == \"\") }","tryCatchPattern":"if err := apiCall(req); err != nil {\n    if strings.HasSuffix(err.Error(), structs.ErrIncompatibleFiltering.Error()) {\n        req.QueryOptions.Prefix = \"\" // keep only the filter expression\n        err = apiCall(req)\n    }\n    return err\n}","preventionTips":["Standardize on filter expressions and remove legacy Prefix usage from client code","Ensure HTTP query builders emit either filter or prefix, never both","Map the server's 400 response for this error in gateway/proxy layers","Add client-side request validation before sending list requests"],"tags":["nomad","filtering","request-validation","http"],"backgroundTag":"incompatible-filter-parameters","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}