{"record":{"id":"c59d51652dbdbd5e","repo":"flowable/flowable-engine","slug":"provided-user-agent-is-null","errorCode":null,"errorMessage":"Provided user agent is null","messagePattern":"Provided user agent is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/TokenQueryImpl.java","lineNumber":137,"sourceCode":"            throw new FlowableIllegalArgumentException(\"Provided ip address is null\");\n        }\n        this.ipAddress = ipAddress;\n        return this;\n    }\n\n    @Override\n    public TokenQuery ipAddressLike(String ipAddressLike) {\n        if (ipAddressLike == null) {\n            throw new FlowableIllegalArgumentException(\"Provided ipAddressLike is null\");\n        }\n        this.ipAddressLike = ipAddressLike;\n        return this;\n    }\n\n    @Override\n    public TokenQuery userAgent(String userAgent) {\n        if (userAgent == null) {\n            throw new FlowableIllegalArgumentException(\"Provided user agent is null\");\n        }\n        this.userAgent = userAgent;\n        return this;\n    }\n\n    @Override\n    public TokenQuery userAgentLike(String userAgentLike) {\n        if (userAgentLike == null) {\n            throw new FlowableIllegalArgumentException(\"Provided userAgentLike is null\");\n        }\n        this.userAgentLike = userAgentLike;\n        return this;\n    }\n\n    @Override\n    public TokenQuery userId(String userId) {\n        if (userId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided user id is null\");","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/TokenQueryImpl.java#L119-L155","documentation":"TokenQueryImpl.userAgent(String) is a query-criteria setter on the Flowable IDM engine's token query API. It validates its argument eagerly and throws FlowableIllegalArgumentException when a null user agent is passed, because a null criteria is indistinguishable from 'no criteria' and would produce an ambiguous query. The library fails fast at query-build time rather than returning wrong or empty results.","triggerScenarios":"Calling TokenQuery.userAgent(null), typically as part of building a createTokenQuery() chain, e.g. identityService.createTokenQuery().userAgent(someVar) where someVar is null.","commonSituations":"Passing an optional request parameter (e.g. a filter taken from an HTTP query string or a User-Agent header) straight into the query builder without checking for null; bean/DTO fields that were never populated; refactors where a previously defaulted variable became nullable.","solutions":["Ensure a non-null user agent is passed (default to a sentinel or computed value if it is genuinely unknown).","Only call userAgent(...) when the value is non-null; skip the criteria to search all tokens.","If empty-string values should be allowed, convert null to \"\" before calling if that matches intended semantics."],"exampleFix":"// before\nString ua = request.getHeader(\"User-Agent\");\nTokenQuery q = identityService.createTokenQuery().userAgent(ua);\n\n// after\nString ua = request.getHeader(\"User-Agent\");\nTokenQuery q = identityService.createTokenQuery();\nif (ua != null) {\n    q = q.userAgent(ua);\n}","handlingStrategy":"validation","validationCode":"if (userAgent == null) { throw new IllegalArgumentException(\"userAgent filter must be non-null or omitted\"); }\nidentityService.createTokenQuery().userAgent(userAgent);","typeGuard":"boolean isValidFilter(String v) { return v != null; }","tryCatchPattern":"try {\n    query.userAgent(ua);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"user agent is null\")) {\n        query = identityService.createTokenQuery(); // drop the criterion\n    } else { throw e; }\n}","preventionTips":["Wrap query building in a helper that skips null criteria.","Never pass raw optional HTTP parameters directly into Flowable query builders.","Use Objects.requireNonNull with a clear message at your own boundary to fail earlier with context."],"tags":["null-check","query-builder","idm-engine","java"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}