flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided correlationId is null

Error message

Provided correlationId is null

What it means

ExternalWorkerJobQueryImpl.correlationId() rejects a null correlation id with FlowableIllegalArgumentException. The correlation id links external worker jobs to their business correlation key; a null filter value is meaningless and would break query construction, so it is validated eagerly.

Solutions

1. Pass a non-null correlation id; skip the filter when it is absent
2. Default the correlation value to a sentinel (e.g. empty string) only if that matches your data model
3. Fix the upstream producer so correlation ids are always set
4. Catch FlowableIllegalArgumentException when building user-driven queries

Example fix

// before
query.correlationId(message.getCorrelationId()); // header may be missing
// after
String correlationId = message.getCorrelationId();
if (correlationId != null) {
    query.correlationId(correlationId);
}

if (correlationId == null) { throw new IllegalArgumentException("correlationId must not be null"); }
query.correlationId(correlationId);

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

try {
    query.correlationId(correlationId);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null correlation id in job query: {}", e.getMessage());
    throw new InvalidQueryException(e);
}

When it happens

Trigger: Calling externalWorkerJobQuery.correlationId(null) directly or within an or() block; passing a message/event correlation value that was never populated.

Common situations: External worker job processing where the correlation value comes from message headers that were missing; dynamic query builders copying fields from DTOs with optional fields.

Related errors

• activity tenant id is null
• activityId is null
• batchId is null
• batchSearchKey is null
• batchSearchKey2 is null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java:368

            this.caseDefinitionKey = caseDefinitionKey;
        }
        return this;
    }

    @Override
    public ExternalWorkerJobQuery 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 ExternalWorkerJobQuery 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 ExternalWorkerJobQuery 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)