flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided correlationId is null

Error message

Provided correlationId is null

What it means

SuspendedJobQueryImpl.correlationId(String) throws FlowableIllegalArgumentException when the supplied correlationId is null. Like other query setters, it validates input at call time so an incomplete filter fails fast instead of silently matching nothing. The value is also routed to the current OR-query object when inside an or() block, so validation happens before either branch.

Solutions

1. Verify the correlation id is actually generated/persisted before querying (check where the job was created).
2. Guard the call site: skip the filter or fall back to another filter (e.g. handlerType, executionId) when the id is null.
3. If the correlation id comes from a request/event, add upstream validation to reject messages without it.

Example fix

// before
SuspendedJobQuery q = jobService.createSuspendedJobQuery().correlationId(msg.getCorrelationId());
// after
if (msg.getCorrelationId() == null) {
    throw new IllegalArgumentException("Message missing correlationId");
}
SuspendedJobQuery q = jobService.createSuspendedJobQuery().correlationId(msg.getCorrelationId());

if (correlationId == null || correlationId.isEmpty()) {
    throw new IllegalArgumentException("correlationId must be non-null to query suspended jobs");
}

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

try {
    return jobService.createSuspendedJobQuery().correlationId(correlationId).list();
} catch (FlowableIllegalArgumentException e) {
    log.warn("Missing correlationId, skipping suspended job lookup");
    return Collections.emptyList();
}

When it happens

Trigger: Calling correlationId(null) directly, or passing a variable holding the job correlation id (e.g. from an event, message header, or external correlation store) that is null, inside or outside an or() block.

Common situations: Message-driven integrations where a correlation id header is missing; lookups of suspended jobs after a failed external-worker enqueue where the correlation key was never assigned.

Related errors

• Provided execution id is null
• Provided handlerType is null
• Provided handlerTypes are null
• Provided job id is null
• Provided job id list is null

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

Appendix: source

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

            this.caseDefinitionKey = caseDefinitionKey;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl 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 SuspendedJobQueryImpl 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 SuspendedJobQueryImpl 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)