{"record":{"id":"ee1d9990b026ac84","repo":"flowable/flowable-engine","slug":"provided-correlationid-is-null-ee1d99","errorCode":null,"errorMessage":"Provided correlationId is null","messagePattern":"Provided correlationId is null","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java","lineNumber":368,"sourceCode":"            this.caseDefinitionKey = caseDefinitionKey;\n        }\n        return this;\n    }\n\n    @Override\n    public ExternalWorkerJobQuery planItemInstanceId(String planItemInstanceId) {\n        if (planItemInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided plan item instance id is null\");\n        }\n        subScopeId(planItemInstanceId);\n        scopeType(ScopeTypes.CMMN);\n        return this;\n    }\n\n    @Override\n    public ExternalWorkerJobQuery correlationId(String correlationId) {\n        if (correlationId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided correlationId is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.correlationId = correlationId;\n        } else {\n            this.correlationId = correlationId;\n        }\n        return this;\n    }\n\n    @Override\n    public ExternalWorkerJobQuery executionId(String executionId) {\n        if (executionId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided execution id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.executionId = executionId;\n        } else {\n            this.executionId = executionId;","sourceCodeStart":350,"sourceCodeEnd":386,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java#L350-L386","documentation":"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.","triggerScenarios":"Calling externalWorkerJobQuery.correlationId(null) directly or within an or() block; passing a message/event correlation value that was never populated.","commonSituations":"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.","solutions":["Pass a non-null correlation id; skip the filter when it is absent","Default the correlation value to a sentinel (e.g. empty string) only if that matches your data model","Fix the upstream producer so correlation ids are always set","Catch FlowableIllegalArgumentException when building user-driven queries"],"exampleFix":"// before\nquery.correlationId(message.getCorrelationId()); // header may be missing\n// after\nString correlationId = message.getCorrelationId();\nif (correlationId != null) {\n    query.correlationId(correlationId);\n}","handlingStrategy":"validation","validationCode":"if (correlationId == null) { throw new IllegalArgumentException(\"correlationId must not be null\"); }\nquery.correlationId(correlationId);","typeGuard":"boolean hasCorrelationId(String correlationId) { return correlationId != null && !correlationId.trim().isEmpty(); }","tryCatchPattern":"try {\n    query.correlationId(correlationId);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"Null correlation id in job query: {}\", e.getMessage());\n    throw new InvalidQueryException(e);\n}","preventionTips":["Ensure message producers always set correlation headers before jobs are queried","Treat correlation id as a required field in your job-processing DTOs","Null-check fields copied from external messages before filtering","Log and skip filters for messages lacking correlation ids rather than querying with null"],"tags":["flowable","null-check","query","external-worker"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}