flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided user agent is null

Error message

Provided user agent is null

What it means

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.

Solutions

1. Ensure a non-null user agent is passed (default to a sentinel or computed value if it is genuinely unknown).
2. Only call userAgent(...) when the value is non-null; skip the criteria to search all tokens.
3. If empty-string values should be allowed, convert null to "" before calling if that matches intended semantics.

Example fix

// before
String ua = request.getHeader("User-Agent");
TokenQuery q = identityService.createTokenQuery().userAgent(ua);

// after
String ua = request.getHeader("User-Agent");
TokenQuery q = identityService.createTokenQuery();
if (ua != null) {
    q = q.userAgent(ua);
}

if (userAgent == null) { throw new IllegalArgumentException("userAgent filter must be non-null or omitted"); }
identityService.createTokenQuery().userAgent(userAgent);

boolean isValidFilter(String v) { return v != null; }

try {
    query.userAgent(ua);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("user agent is null")) {
        query = identityService.createTokenQuery(); // drop the criterion
    } else { throw e; }
}

When it happens

Trigger: Calling TokenQuery.userAgent(null), typically as part of building a createTokenQuery() chain, e.g. identityService.createTokenQuery().userAgent(someVar) where someVar is null.

Common situations: 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.

Related errors

• Provided first name is null
• Provided id is null
• Provided ids is null
• Provided token data is null
• Provided tokenDataLike is null

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/c59d51652dbdbd5e. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/TokenQueryImpl.java:137

            throw new FlowableIllegalArgumentException("Provided ip address is null");
        }
        this.ipAddress = ipAddress;
        return this;
    }

    @Override
    public TokenQuery ipAddressLike(String ipAddressLike) {
        if (ipAddressLike == null) {
            throw new FlowableIllegalArgumentException("Provided ipAddressLike is null");
        }
        this.ipAddressLike = ipAddressLike;
        return this;
    }

    @Override
    public TokenQuery userAgent(String userAgent) {
        if (userAgent == null) {
            throw new FlowableIllegalArgumentException("Provided user agent is null");
        }
        this.userAgent = userAgent;
        return this;
    }

    @Override
    public TokenQuery userAgentLike(String userAgentLike) {
        if (userAgentLike == null) {
            throw new FlowableIllegalArgumentException("Provided userAgentLike is null");
        }
        this.userAgentLike = userAgentLike;
        return this;
    }

    @Override
    public TokenQuery userId(String userId) {
        if (userId == null) {
            throw new FlowableIllegalArgumentException("Provided user id is null");

View on GitHub (pinned to d6d39ce1c6)