flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided userAgentLike is null

Error message

Provided userAgentLike is null

What it means

TokenQueryImpl.userAgentLike(String) adds a fuzzy-match (LIKE) criterion on the token's user agent. Passing null is rejected with FlowableIllegalArgumentException because a null 'like' pattern is meaningless and would be ambiguous with not filtering at all. The check is done eagerly when building the query.

Solutions

1. Pass a non-null pattern, e.g. "%Chrome%" for substring matching.
2. Conditionally apply the criterion only when the filter value is non-null.
3. If the caller intended 'match everything', omit userAgentLike entirely instead of passing null.

Example fix

// before
TokenQuery q = identityService.createTokenQuery().userAgentLike(filter.userAgentLike);

// after
TokenQuery q = identityService.createTokenQuery();
if (filter.userAgentLike != null) {
    q = q.userAgentLike("%" + filter.userAgentLike + "%");
}

if (userAgentLike == null) { userAgentLike = "%"; } // or skip the call
identityService.createTokenQuery().userAgentLike(userAgentLike);

boolean hasPattern(String v) { return v != null && !v.isEmpty(); }

try {
    query.userAgentLike(pattern);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("userAgentLike is null")) { /* skip criterion */ } else { throw e; }
}

When it happens

Trigger: Calling TokenQuery.userAgentLike(null) inside a createTokenQuery() chain, usually with a variable or optional filter value that is null.

Common situations: Dynamic search forms where the 'user agent contains' field is optional; mapping a search DTO whose property was never set; copy-pasted query-building code applying all criteria unconditionally.

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/0ceb8abcaddf2a1e. Report an issue: GitHub.

Appendix: source

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

            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");
        }
        this.userId = userId;
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)