flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided exception message is null

Error message

Provided exception message is null

What it means

exceptionMessage(String) narrows the suspended-job query to jobs whose failure carries the given exception message. Null is rejected with FlowableIllegalArgumentException because matching against a null message is undefined; the query builder fails fast.

Source

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

            noRetriesLeft = true;
        }
        return this;
    }

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

    @Override
    public SuspendedJobQueryImpl exceptionMessage(String exceptionMessage) {
        if (exceptionMessage == null) {
            throw new FlowableIllegalArgumentException("Provided exception message is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.exceptionMessage = exceptionMessage;
        } else {
            this.exceptionMessage = exceptionMessage;
        }
        return this;
    }

    @Override
    public SuspendedJobQueryImpl jobTenantId(String tenantId) {
        if (tenantId == null) {
            throw new FlowableIllegalArgumentException("Provided tenant id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.tenantId = tenantId;
        } else {
            this.tenantId = tenantId;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null string; use an empty string only if that is truly the stored value.
2. If filtering by exception is optional, skip the call when the message is null.
3. Fall back to a meaningful default (e.g. exception class name) when getMessage() is null.
4. Use exceptionStackTrace() or jobExceptionMessageLike-style matching if exact message is unavailable.

Example fix

// before
query.exceptionMessage(e.getMessage()); // may be null
// after
String msg = e.getMessage() != null ? e.getMessage() : e.getClass().getName();
query.exceptionMessage(msg);

if (exceptionMessage == null) {
    throw new IllegalArgumentException("exceptionMessage requires a non-null string");
}

boolean hasMessage(Throwable t) { return t != null && t.getMessage() != null; }

try {
    query.exceptionMessage(msg);
} catch (FlowableIllegalArgumentException e) {
    // fall back to a non-null representation
    query.exceptionMessage("unknown");
}

When it happens

Trigger: Calling query.exceptionMessage(msg) with msg == null, e.g. taking the message from a caught exception where getMessage() returned null, or from an absent configuration value.

Common situations: Dead-letter monitoring dashboards filtering by failure reason; NullPointerException-derived messages (getMessage() returns null for NPEs constructed without a message) passed straight into the query.

Related errors

• Cannot combine onlyExternalWorkers() with onlyMessages() in
• Cannot combine onlyMessages() with onlyExternalWorkers() in
• Cannot combine onlyTimers() with onlyExternalWorkers() in th
• Provided date is null
• Provided exception message is null

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