flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided correlationId is null

Error message

Provided correlationId is null

What it means

JobQueryImpl.correlationId(String) validates that the correlation id filter is non-null and throws FlowableIllegalArgumentException otherwise. The correlation id links jobs (e.g. async/external jobs) to business correlations, and a null filter would be meaningless, so it is rejected at query build time. The value is stored on the query or the active or-query object depending on whether the call happens inside an or() block.

Solutions

1. Ensure the correlation id is set on the source message/payload before querying
2. Null-check and skip the correlationId filter, falling back to other filters
3. Populate correlation ids when creating jobs so downstream queries always have one
4. Trace where the value is read from (header/config) and add validation there

Example fix

// before
jobQuery.correlationId(message.getCorrelationId()); // may be null
// after
String cid = message.getCorrelationId();
if (cid != null && !cid.isEmpty()) {
    jobQuery.correlationId(cid);
}

if (correlationId == null || correlationId.isEmpty()) { throw new IllegalArgumentException("correlationId must not be null/empty"); }
jobQuery.correlationId(correlationId);

boolean hasCorrelationId(String c) { return c != null && !c.isEmpty(); }

try {
    jobQuery.correlationId(correlationId);
} catch (FlowableIllegalArgumentException e) {
    logger.warn("correlationId was null", e);
}

When it happens

Trigger: Calling jobQuery.correlationId(null); typically when the correlation id comes from message metadata, a header, or a config property that was missing; also inside or(...) compositions.

Common situations: Message/event payload lacked the correlation header; upgrade where correlationId support was newly introduced and older records/payloads carry null; generic query builders passing optional fields through.

Related errors

• Involved groups are null
• Provided batch id is null
• Provided batch type is null
• Provided batch types must be provided and not empty
• Provided exception message is null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/JobQueryImpl.java:360

            this.caseDefinitionKey = caseDefinitionKey;
        }
        return this;
    }

    @Override
    public JobQueryImpl planItemInstanceId(String planItemInstanceId) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("Provided plan item instance id is null");
        }
        subScopeId(planItemInstanceId);
        scopeType(ScopeTypes.CMMN);
        return this;
    }

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

    @Override
    public JobQueryImpl executionId(String executionId) {
        if (executionId == null) {
            throw new FlowableIllegalArgumentException("Provided execution id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.executionId = executionId;
        } else {
            this.executionId = executionId;

View on GitHub (pinned to d6d39ce1c6)