flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided handlerType is null

Error message

Provided handlerType is null

What it means

FlowableIllegalArgumentException thrown by JobQueryImpl.handlerType(String) when the handlerType argument is null. Flowable validates all query filter arguments up front so that an invalid query fails immediately at construction time rather than producing a broken SQL query or empty result set at execution. A null handlerType is never a meaningful filter value.

Solutions

1. Pass a concrete handler type string (e.g. "message" or "timer") to handlerType().
2. Guard the call: only invoke handlerType() when the value is non-null, otherwise skip adding this filter.
3. Check the source of the value (config/property/request param) and provide a sensible default before building the query.

Example fix

// before
String type = properties.get("jobHandlerType");
query.handlerType(type);

// after
String type = properties.get("jobHandlerType");
if (type != null) {
    query.handlerType(type);
}

if (handlerType == null || handlerType.isEmpty()) {
    throw new IllegalArgumentException("handlerType must be a non-empty string before calling handlerType()");
}
query.handlerType(handlerType);

boolean hasHandlerType = handlerType instanceof String && !((String) handlerType).isEmpty();

try {
    query.handlerType(handlerType);
} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {
    log.warn("Invalid handlerType filter: {}", e.getMessage());
}

When it happens

Trigger: Calling jobQuery.handlerType(null) directly, or passing a variable/constant that resolves to null (e.g. a config-driven handler type that was never set) into handlerType().

Common situations: Building dynamic queries where the job handler type comes from configuration, a database column, or a REST request parameter that is optional upstream but mandatory here; refactoring that renamed handler types leaving a null default.

Related errors

• appsDefinitionIds is null
• Business status is null
• Case definition keys is null
• category is null
• parentScopeIds is null or empty

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/JobQueryImpl.java:386

    }

    @Override
    public JobQueryImpl executionId(String executionId) {
        if (executionId == null) {
            throw new FlowableIllegalArgumentException("Provided execution id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.executionId = executionId;
        } else {
            this.executionId = executionId;
        }
        return this;
    }

    @Override
    public JobQueryImpl handlerType(String handlerType) {
        if (handlerType == null) {
            throw new FlowableIllegalArgumentException("Provided handlerType is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.handlerType = handlerType;
        } else {
            this.handlerType = handlerType;
        }
        return this;
    }

    @Override
    public JobQuery handlerTypes(Collection<String> handlerTypes) {
        if (handlerTypes == null) {
            throw new FlowableIllegalArgumentException("Provided handlerTypes are null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.handlerTypes = handlerTypes;
        } else {
            this.handlerTypes = handlerTypes;

View on GitHub (pinned to d6d39ce1c6)