{"record":{"id":"216b17e7079abba9","repo":"flowable/flowable-engine","slug":"process-instance-id-is-null-216b17","errorCode":null,"errorMessage":"Process instance id is null","messagePattern":"Process instance id is null","errorType":"validation","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":99,"sourceCode":"    // Unused, see dynamic query\n    protected String activityId;\n    protected List<EventSubscriptionQueryValue> eventSubscriptions;\n\n    public ProcessInstanceQueryImpl() {\n    }\n\n    public ProcessInstanceQueryImpl(CommandContext commandContext) {\n        super(commandContext);\n    }\n\n    public ProcessInstanceQueryImpl(CommandExecutor commandExecutor) {\n        super(commandExecutor);\n    }\n\n    @Override\n    public ProcessInstanceQueryImpl processInstanceId(String processInstanceId) {\n        if (processInstanceId == null) {\n            throw new ActivitiIllegalArgumentException(\"Process instance id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.executionId = processInstanceId;\n        } else {\n            this.executionId = processInstanceId;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processInstanceIds(Set<String> processInstanceIds) {\n        if (processInstanceIds == null) {\n            throw new ActivitiIllegalArgumentException(\"Set of process instance ids is null\");\n        }\n        if (processInstanceIds.isEmpty()) {\n            throw new ActivitiIllegalArgumentException(\"Set of process instance ids is empty\");\n        }\n","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java#L81-L117","documentation":"processInstanceId(id) sets a process-instance filter on the query, internally mapped to the execution id. It throws ActivitiIllegalArgumentException('Process instance id is null') when the id argument is null, since a null id cannot filter and would silently return wrong results.","triggerScenarios":"Calling ProcessInstanceQuery.processInstanceId(null), e.g. from code following a runtimeService.startProcessInstance...() call whose returned instance was null, or from a request parameter that was never provided.","commonSituations":"REST endpoints taking a processInstanceId query/path parameter that the client omitted; jobs processing messages that lost the correlation id.","solutions":["Pass the actual process instance id string obtained from the start/process call","Validate request input (400 Bad Request on missing id) before building the query","Check the upstream variable producing the id (failed start, lost message property)","Catch ActivitiIllegalArgumentException to return a meaningful client error"],"exampleFix":"// before\nProcessInstance pi = runtimeService.startProcessInstanceByKey(\"order\");\nhistoryService.createHistoricProcessInstanceQuery().processInstanceId(pi.getId()); // pi can be null\n// after\nif (pi != null) {\n    historyService.createHistoricProcessInstanceQuery().processInstanceId(pi.getId());\n}","handlingStrategy":"validation","validationCode":"if (processInstanceId == null || processInstanceId.isEmpty()) {\n    throw new IllegalArgumentException(\"processInstanceId is required\");\n}\nquery.processInstanceId(processInstanceId);","typeGuard":"boolean hasId(String id) { return id != null && !id.trim().isEmpty(); }","tryCatchPattern":"try {\n    query.processInstanceId(pid);\n} catch (ActivitiIllegalArgumentException e) {\n    throw new BadRequestException(\"processInstanceId parameter is mandatory\");\n}","preventionTips":["Validate REST parameters with bean validation (@NotBlank) before the engine call","Check startProcessInstance...() return value before using its id","Never propagate possibly-null correlation ids into queries"],"tags":["java","activiti","query","null-argument","process-instance"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}