What causes "Provided handlerTypes are null" in flowable/flowable-engine?

Pass an explicit non-null collection (Collections.emptyList() or Arrays.asList(...)).

flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided handlerTypes are null

Error message

Provided handlerTypes are null

What it means

SuspendedJobQueryImpl.handlerTypes(Collection<String>) throws FlowableIllegalArgumentException when the collection itself is null. Note it validates only nullness of the collection (an empty collection is accepted); passing null would otherwise corrupt the query filter. As with other setters the value is assigned to the current OR-query object when inside an or() block.

Solutions

Pass an explicit non-null collection (Collections.emptyList() or Arrays.asList(...)).
Coalesce null collections at the call site before invoking handlerTypes.
If a null list means 'no filter', add a conditional so the setter is skipped entirely instead of called with null.

Example fix

// before
query.handlerTypes(selectedTypes); // NPE-style throw when selectedTypes == null
// after
if (selectedTypes != null && !selectedTypes.isEmpty()) {
    query.handlerTypes(selectedTypes);
}

Defensive patterns

Strategy: validation

Validate before calling

if (handlerTypes == null) {
    handlerTypes = Collections.emptyList();
}

Type guard

Collection<String> nonNullTypes(Collection<String> types) { return types == null ? Collections.emptyList() : types; }

Try / catch

try {
    query.handlerTypes(handlerTypes);
} catch (FlowableIllegalArgumentException e) {
    // handlerTypes was null; query without the handler-type filter
}

Prevention

Initialize handler-type collections eagerly (empty list, not null).
Null-coalesce config- or request-derived lists at the boundary.
Prefer Optional<Collection<String>> internally and unwrap with a default.

When it happens

Trigger: Calling handlerTypes(null) directly, or passing a Collection built from config/user input (e.g. a List<String> parsed from a comma-separated property or request parameter) that was never initialized.

Common situations: Filtering suspended jobs by several handler types in admin dashboards where the selected-types list is empty-initialized as null instead of Collections.emptyList(); refactors where a nullable list is forwarded without a check.

Related errors

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java:409

    }

    @Override
    public SuspendedJobQueryImpl 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 SuspendedJobQueryImpl 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 SuspendedJobQueryImpl withRetriesLeft() {
        if (inOrStatement) {
            this.currentOrQueryObject.retriesLeft = true;
        } else {
            retriesLeft = true;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)