flowable/flowable-engine · error · FlowableIllegalArgumentException

correlationId is null

Error message

correlationId is null

What it means

GetJobByCorrelationIdCmd throws FlowableIllegalArgumentException when correlationId is null. It searches dead-letter jobs (and fallback entity managers) for a job whose correlation id matches; a null correlation id cannot identify any job and is rejected before querying.

Solutions

1. Ensure the correlation id is extracted and non-null before calling the lookup.
2. Check how the job was created — if no correlation id was set at creation, lookup by correlation id cannot work.
3. Guard message-processing code to reject/dlq messages without a correlation id header.
4. Log the incoming correlation id at the entry point to find where it is lost.

Example fix

// before
Job job = cmdExecutor.execute(new GetJobByCorrelationIdDto(correlationId).toCmd(cfg)); // correlationId null
// after
if (correlationId == null) {
    throw new IllegalArgumentException("correlationId required for job lookup");
}
Job job = cmdExecutor.execute(new GetJobByCorrelationIdCmd(correlationId, cfg));

if (correlationId == null || correlationId.isBlank()) { throw new IllegalArgumentException("correlationId required"); }

try { Job job = commandExecutor.execute(new GetJobByCorrelationIdCmd(correlationId, cfg)); } catch (FlowableIllegalArgumentException e) { /* missing correlation id */ }

When it happens

Trigger: Executing new GetJobByCorrelationIdCmd(null, cfg) or job-service APIs that look up jobs by correlation id with a null value; message-driven flows where the correlation id header was absent.

Common situations: Middleware/integration code that failed to propagate a correlation id from the incoming message; jobs created without a correlation id then looked up by one; configuration where the correlation id extractor returns null.

Related errors

• historyJobId is null
• historyJobId is null
• jobId is null
• jobId is null
• jobId is null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/cmd/GetJobByCorrelationIdCmd.java:38

/**
 * @author Filip Hrisafov
 */
public class GetJobByCorrelationIdCmd implements Command<Job> {
    
    protected JobServiceConfiguration jobServiceConfiguration;

    protected String correlationId;

    public GetJobByCorrelationIdCmd(String correlationId, JobServiceConfiguration jobServiceConfiguration) {
        this.correlationId = correlationId;
        this.jobServiceConfiguration = jobServiceConfiguration;
    }

    @Override
    public Job execute(CommandContext commandContext) {
        if (correlationId == null) {
            throw new FlowableIllegalArgumentException("correlationId is null");
        }

        Job job = jobServiceConfiguration.getDeadLetterJobEntityManager().findJobByCorrelationId(correlationId);
        if (job != null) {
            return job;
        }

        job = jobServiceConfiguration.getExternalWorkerJobEntityManager().findJobByCorrelationId(correlationId);
        if (job != null) {
            return job;
        }

        job = jobServiceConfiguration.getTimerJobEntityManager().findJobByCorrelationId(correlationId);
        if (job != null) {
            return job;
        }

        job = jobServiceConfiguration.getSuspendedJobEntityManager().findJobByCorrelationId(correlationId);

View on GitHub (pinned to d6d39ce1c6)