flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot combine onlyMessages() with onlyExternalWorkers() in…

Error message

Cannot combine onlyMessages() with onlyExternalWorkers() in the same query

What it means

SuspendedJobQueryImpl.externalWorkers() throws FlowableIllegalArgumentException when onlyMessages was already set. The three job-kind filters (timers, messages, externalWorkers) are mutually exclusive; externalWorkers() after messages() fails fast with this error before the query is executed.

Solutions

Call at most one of messages(), timers(), externalWorkers() per query.
Run separate queries per job kind and merge results for combined views.
In multi-select UIs, enforce single-kind selection or fan out into multiple queries.

Example fix

// before
jobService.createSuspendedJobQuery().messages().externalWorkers(); // throws
// after
List<Job> all = new ArrayList<>();
all.addAll(jobService.createSuspendedJobQuery().messages().list());
all.addAll(jobService.createSuspendedJobQuery().externalWorkers().list());

Defensive patterns

Strategy: type-guard

Validate before calling

if (onlyMessagesAlreadyApplied) {
    query = jobService.createSuspendedJobQuery(); // fresh query for externalWorkers()
}

Type guard

boolean canApplyExternalWorkers(boolean messagesSet) { return !messagesSet; }

Try / catch

try {
    q.messages().externalWorkers();
} catch (FlowableIllegalArgumentException e) {
    q = jobService.createSuspendedJobQuery().externalWorkers();
}

Prevention

Apply exactly one kind filter per SuspendedJobQuery instance.
Use a builder helper that maps a single kind enum to one filter call.
Fan out multiple queries and merge lists for combined kind coverage.

When it happens

Trigger: Chaining .messages().externalWorkers() on the same SuspendedJobQueryImpl instance (order-independent with the other kind setters), including within or() scopes.

Common situations: Acquiring suspended external-worker jobs in worker-pool code that previously queried message jobs and simply appended the new filter; dynamic admin filters that allow multi-select of job kinds.

Related errors

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

Appendix: source

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

            throw new FlowableIllegalArgumentException("Cannot combine onlyTimers() with onlyMessages() in the same query");
        }

        if (onlyExternalWorkers) {
            throw new FlowableIllegalArgumentException("Cannot combine onlyExternalWorkers() with onlyMessages() in the same query");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.onlyMessages = true;
        } else {
            this.onlyMessages = true;
        }
        return this;
    }

    @Override
    public SuspendedJobQueryImpl externalWorkers() {
        if (onlyMessages) {
            throw new FlowableIllegalArgumentException("Cannot combine onlyMessages() with onlyExternalWorkers() in the same query");
        }

        if (onlyTimers) {
            throw new FlowableIllegalArgumentException("Cannot combine onlyTimers() with onlyExternalWorkers() in the same query");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.onlyExternalWorkers = true;
        } else {
            this.onlyExternalWorkers = true;
        }
        return this;
    }

    @Override
    public SuspendedJobQueryImpl duedateHigherThan(Date date) {
        if (date == null) {
            throw new FlowableIllegalArgumentException("Provided date is null");

View on GitHub (pinned to d6d39ce1c6)