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

DeadLetterJobQueryImpl.externalWorkers() rejects a query that already narrowed to message jobs. If the onlyMessages flag is set, calling externalWorkers() would combine two exclusive categories, so FlowableIllegalArgumentException is thrown. A dead-letter job query can target only one job category.

Source

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

            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 DeadLetterJobQueryImpl 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 DeadLetterJobQueryImpl duedateHigherThan(Date date) {
        if (date == null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Use only one of messages(), timers(), externalWorkers() per query
2. Pick the category once with if/else logic before chaining other criteria
3. Start a new DeadLetterJobQueryImpl for a different category

Example fix

// before
DeadLetterJobQuery q = mgmt.createDeadLetterJobQuery().messages();
if (useExternal) { q.externalWorkers(); }
// after
DeadLetterJobQuery q = useExternal ? mgmt.createDeadLetterJobQuery().externalWorkers() : mgmt.createDeadLetterJobQuery().messages();

if (useMessages && useExternalWorkers) { throw new IllegalArgumentException("messages() and externalWorkers() are mutually exclusive"); }

try { query = mgmt.createDeadLetterJobQuery().externalWorkers(); } catch (FlowableIllegalArgumentException e) { log.error("Conflicting category filters", e); }

When it happens

Trigger: Calling deadLetterJobQuery().messages() ... .externalWorkers(). The check fires in externalWorkers() when onlyMessages is true.

Common situations: Building the filter chain conditionally where multiple category flags can be requested; code reuse where a query configured for messages is later extended for external workers.

Related errors

• Cannot combine onlyExternalWorkers() with onlyMessages() in
• Cannot combine onlyTimers() with onlyExternalWorkers() in th
• baseUrl can not be null
• Could not find an app definition with id '<appDefinitionId>'
• Invalid action: '<action>'.

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