flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided token value is null

Error message

Provided token value is null

What it means

Flowable's TokenQueryImpl.tokenValue(String tokenValue) throws FlowableIllegalArgumentException when the tokenValue argument is null. Query criteria must be non-null so they can be bound as SQL parameters. The check occurs at query-build time, not at execution time.

Source

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

            throw new FlowableIllegalArgumentException("Provided id is null");
        }
        this.id = id;
        return this;
    }

    @Override
    public TokenQuery tokenIds(List<String> ids) {
        if (ids == null) {
            throw new FlowableIllegalArgumentException("Provided ids is null");
        }
        this.ids = ids;
        return this;
    }

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

    @Override
    public TokenQuery tokenDate(Date tokenDate) {
        if (tokenDate == null) {
            throw new FlowableIllegalArgumentException("Provided token date is null");
        }
        this.tokenDate = tokenDate;
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the token value before querying and handle the missing-value case in application logic
2. Omit the tokenValue criterion when null if a broader query is acceptable
3. Ensure values are read from the correct source (header/config) so they are not null by mistake

Example fix

// before
TokenQuery query = identityService.createTokenQuery().tokenValue(value);
// after
TokenQuery query = identityService.createTokenQuery();
if (value != null) {
    query.tokenValue(value);
}

if (tokenValue == null) { throw new IllegalArgumentException("tokenValue must not be null before tokenValue()"); }

boolean hasTokenValue(String tokenValue) { return tokenValue != null && !tokenValue.isEmpty(); }

try { query.tokenValue(value); } catch (FlowableIllegalArgumentException e) { log.warn("Invalid token query: {}", e.getMessage()); }

When it happens

Trigger: Calling tokenValue(null) on a TokenQuery, typically when the token value originated from a nullable source such as a request header, a decoded JWT field, or an unset entity attribute.

Common situations: Searching for tokens by value where the value was stripped by a sanitizer; passing a variable that was never assigned; upstream services returning null for missing values that were forwarded unchanged.

Related errors

• Provided id is null
• Provided ids is null
• Provided token date is null
• Provided tokenDateBefore is null
• Provided tokenDateAfter is null

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