flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot combine onlyTimers() with onlyMessages() in the same…

Error message

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

What it means

SuspendedJobQueryImpl.timers() throws FlowableIllegalArgumentException when the query was already narrowed with onlyMessages(). Job kind filters are mutually exclusive: a query can select timers, messages, or external-worker jobs, but not a combination. Flowable detects the conflict at query-build time and fails fast rather than producing contradictory SQL.

Solutions

Call only one of timers(), messages(), or externalWorkers() per query.
If you need both timers and messages, run two queries and merge results in application code.
Remove the redundant/conflicting call from the builder chain.

Example fix

// before
jobService.createSuspendedJobQuery().messages().timers(); // throws
// after
jobService.createSuspendedJobQuery().messages(); // or .timers(), not both

Defensive patterns

Strategy: type-guard

Validate before calling

boolean kindAlreadySet = onlyMessages || onlyTimers || onlyExternalWorkers;
if (kindAlreadySet) throw new IllegalStateException("Job kind filter already set; cannot add another");

Type guard

boolean canApplyTimers(SuspendedJobQueryImpl q) { return !q.isOnlyMessages() && !q.isOnlyExternalWorkers(); }

Try / catch

try {
    query.messages().timers();
} catch (FlowableIllegalArgumentException e) {
    // split into two queries instead
}

Prevention

Never chain more than one of timers()/messages()/externalWorkers().
Track which kind filter was applied in your own builder wrapper to prevent double calls.
Use separate query executions to union different job kinds.

When it happens

Trigger: Chaining .messages().timers() (in either order) on the same SuspendedJobQueryImpl instance, including inside an or() block where the flags live on the same query object.

Common situations: Developers assuming the filters are additive (like category filters) and calling both to mean 'timers OR messages'; copy-paste of query-builder chains where an extra .timers() was left behind.

Related errors

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

Appendix: source

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

            retriesLeft = true;
        }
        return this;
    }

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

    @Override
    public SuspendedJobQueryImpl timers() {
        if (onlyMessages) {
            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.onlyTimers = true;
        } else {
            this.onlyTimers = true;
        }
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)