flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided handlerType is null

Error message

Provided handlerType is null

What it means

SuspendedJobQueryImpl.handlerType(String) throws FlowableIllegalArgumentException when the supplied handlerType is null. The handler type (e.g. the async-continuation or external-worker handler type) is a mandatory non-null string for this filter; Flowable rejects nulls eagerly so the query builder fails at configuration time rather than during execution.

Solutions

1. Pass a concrete handler type constant from HandlerTypes (e.g. HandlerTypes.ASYNC_CONTINUATION or your external-worker type).
2. Validate configuration loading: if handlerType comes from a property, default it or fail at startup with a clear message.
3. If you want to match multiple handler types, use handlerTypes(Collection) with a non-null, non-empty collection.

Example fix

// before
String type = props.getProperty("job.handlerType");
query.handlerType(type); // throws when property missing
// after
String type = props.getProperty("job.handlerType", HandlerTypes.ASYNC_CONTINUATION);
query.handlerType(type);

if (handlerType == null) {
    handlerType = HandlerTypes.ASYNC_CONTINUATION; // or fail fast with a clear message
}

boolean isValidHandlerType(String t) { return t != null && HandlerTypes.getAllJobHandlerTypes().contains(t); }

try {
    query.handlerType(handlerType);
} catch (FlowableIllegalArgumentException e) {
    throw new ConfigurationException("job.handlerType is not configured", e);
}

When it happens

Trigger: Calling handlerType(null), e.g. passing a handler type read from configuration (process XML extension attribute, Spring property, or constants class) where the property is undefined, or passing an enum lookup that resolved to null.

Common situations: Misconfigured external-worker setups where the expected handler type constant changed between Flowable versions; typing the wrong property key when loading the handler type from config.

Related errors

• Provided correlationId is null
• Provided execution id is null
• Provided handlerTypes are null
• Provided job id is null
• Provided job id list is null

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

Appendix: source

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

    }

    @Override
    public SuspendedJobQueryImpl 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 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;

View on GitHub (pinned to d6d39ce1c6)