{"record":{"id":"6e326c5238cf0a33","repo":"flowable/flowable-engine","slug":"provided-process-definition-id-is-null-6e326c","errorCode":null,"errorMessage":"Provided process definition id is null","messagePattern":"Provided process definition id 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":149,"sourceCode":"            this.processInstanceId = processInstanceId;\n        }\n        return this;\n    }\n    \n    @Override\n    public ExternalWorkerJobQuery withoutProcessInstanceId() {\n        if (inOrStatement) {\n            this.currentOrQueryObject.withoutProcessInstanceId = true;\n        } else {\n            this.withoutProcessInstanceId = true;\n        }\n        return this;\n    }\n\n    @Override\n    public ExternalWorkerJobQuery processDefinitionId(String processDefinitionId) {\n        if (processDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided process definition id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionId = processDefinitionId;\n        } else {\n            this.processDefinitionId = processDefinitionId;\n        }\n        return this;\n    }\n\n    @Override\n    public ExternalWorkerJobQuery processDefinitionKey(String processDefinitionKey) {\n        if (processDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Provided process definition key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.processDefinitionKey = processDefinitionKey;\n        } else {\n            this.processDefinitionKey = processDefinitionKey;","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java#L131-L167","documentation":"ExternalWorkerJobQuery.processDefinitionId(String) throws FlowableIllegalArgumentException when the provided process definition id is null. Flowable validates query parameters eagerly so null ids never reach the persistence layer. A null definition id is treated as a caller bug, not an empty filter.","triggerScenarios":"Calling externalWorkerJobQuery().processDefinitionId(null), e.g. when the definition id was resolved from a deployment step or repository lookup that failed silently.","commonSituations":"Monitoring dashboards that filter jobs by definition where the definition is chosen dynamically; migration scripts with missing definition metadata; passing a null from configuration that was not filled in.","solutions":["Resolve the process definition id via RepositoryService before querying and verify it is non-null.","Guard the call site: only call processDefinitionId(id) when id != null.","Use processDefinitionKey instead if you filter by key and the id is unavailable (with its own null check).","Fix the upstream lookup that returns null (wrong tenant/deployment)."],"exampleFix":"// before\nquery.processDefinitionId(definition.getId());\n// after\nif (definition != null && definition.getId() != null) {\n    query.processDefinitionId(definition.getId());\n}","handlingStrategy":"validation","validationCode":"if (definitionId != null && !definitionId.isBlank()) {\n    query.processDefinitionId(definitionId);\n}","typeGuard":"boolean isValidDefinitionId(String id) { return id != null && id.matches(\"[a-zA-Z0-9_-]+(:[0-9]+)*.*\"); }","tryCatchPattern":"try {\n    query.processDefinitionId(definitionId);\n} catch (FlowableIllegalArgumentException e) {\n    throw new IllegalArgumentException(\"processDefinitionId must be provided\", e);\n}","preventionTips":["Fetch the definition via RepositoryService.createProcessDefinitionQuery() and check existence first.","Never trust config/deployment metadata for ids without a null check.","Prefer filtering by key when ids are not stable across deployments."],"tags":["flowable","query-builder","null-check","process-definition"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}