flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided category is null

Error message

Provided category is null

What it means

DeadLetterJobQueryImpl.category() throws FlowableIllegalArgumentException when the category parameter is null. Flowable validates query filter arguments at setter time so malformed queries surface immediately instead of failing later in the MyBatis mapping. A null category is not treated as 'no filter'; omitting the call is how you express that.

Solutions

1. Guard the call: only invoke category(...) when the value is non-null
2. Omit the category filter entirely if null should mean 'all categories'
3. Normalize input so an absent category becomes an empty skip rather than null
4. Fix the upstream source (BPMN attribute, config, DTO) that yields the null category

Example fix

// before
DeadLetterJobQuery query = jobService.createDeadLetterJobQuery().category(jobCategory);

// after
DeadLetterJobQuery query = jobService.createDeadLetterJobQuery();
if (jobCategory != null) {
    query = query.category(jobCategory);
}

if (category != null && !category.trim().isEmpty()) {
    query = query.category(category);
}

boolean hasCategory(String category) { return category != null && !category.trim().isEmpty(); }

try {
    return jobService.createDeadLetterJobQuery().category(category).list();
} catch (FlowableIllegalArgumentException e) {
    log.warn("Rejecting dead-letter job query: {}", e.getMessage());
    return Collections.emptyList();
}

When it happens

Trigger: Calling deadLetterJobQuery().category(null), or forwarding a null category variable obtained from a message/event category, configuration, or request parameter into the query builder.

Common situations: Category values read from message definitions or BPMN XML attributes that are absent; REST query endpoints passing optional category fields straight through; copied query code where a category constant was deleted or renamed.

Related errors

• Error retrieving app engine info
• ids are null
• implementation is null
• key is null
• keyLike is null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java:174

    }

    @Override
    public DeadLetterJobQueryImpl processDefinitionKey(String processDefinitionKey) {
        if (processDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Provided process definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKey = processDefinitionKey;
        } else {
            this.processDefinitionKey = processDefinitionKey;
        }
        return this;
    }
    
    @Override
    public DeadLetterJobQueryImpl category(String category) {
        if (category == null) {
            throw new FlowableIllegalArgumentException("Provided category is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.category = category;
        } else {
            this.category = category;
        }
        return this;
    }
    
    @Override
    public DeadLetterJobQueryImpl categoryLike(String categoryLike) {
        if (categoryLike == null) {
            throw new FlowableIllegalArgumentException("Provided categoryLike is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.categoryLike = categoryLike;
        } else {
            this.categoryLike = categoryLike;

View on GitHub (pinned to d6d39ce1c6)