flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided handlerTypes are null

Error message

Provided handlerTypes are null

What it means

DeadLetterJobQuery.handlerTypes(Collection<String>) throws FlowableIllegalArgumentException when the handlerTypes collection itself is null. This is the multi-value variant of handlerType() used for IN-style filtering; a null collection is rejected at construction time. Note the check is on the collection reference, not on its elements.

Solutions

1. Pass an empty collection or skip the call entirely when no types are selected, instead of null.
2. Initialize collections with Collections.emptyList()/List.of() at declaration so they are never null.
3. If a null collection is possible, guard with if (types != null) query.handlerTypes(types).

Example fix

// before
query.handlerTypes(selectedTypes); // selectedTypes may be null
// after
if (selectedTypes != null && !selectedTypes.isEmpty()) {
    query.handlerTypes(selectedTypes);
}

Collection<String> types = Optional.ofNullable(selectedTypes).orElse(Collections.emptyList());
if (!types.isEmpty()) { query.handlerTypes(types); }

boolean hasHandlerTypes(Collection<String> c) { return c != null && !c.isEmpty(); }

try { query.handlerTypes(types); } catch (FlowableIllegalArgumentException e) { log.warn("Null handlerTypes collection supplied"); }

When it happens

Trigger: Calling deadLetterJobQuery().handlerTypes(null), typically when a list built from configuration, a request, or a stream collector ended up null rather than empty, including within or() blocks.

Common situations: Deserialized config object with a null list field; Optional misused so orElse(null) produced null; frameworks binding empty request params to null.

Related errors

• configurations are null
• ids are null
• Provided handlerTypes are null
• Provided job id list is null
• Provided scope ids are null

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

Appendix: source

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

    }

    @Override
    public DeadLetterJobQueryImpl 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 DeadLetterJobQuery handlerTypes(Collection<String> handlerTypes) {
        if (handlerTypes == null) {
            throw new FlowableIllegalArgumentException("Provided handlerTypes are null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.handlerTypes = handlerTypes;
        } else {
            this.handlerTypes = handlerTypes;
        }
        return this;
    }

    @Override
    public DeadLetterJobQueryImpl executable() {
        if (inOrStatement) {
            this.currentOrQueryObject.executable = true;
        } else {
            this.executable = true;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)