{"record":{"id":"fb92eb4b303afb53","repo":"flowable/flowable-engine","slug":"business-key-is-null-fb92eb","errorCode":null,"errorMessage":"Business key is null","messagePattern":"Business key is null","errorType":"validation","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ExecutionQueryImpl.java","lineNumber":152,"sourceCode":"            throw new ActivitiIllegalArgumentException(\"Process definition version is null\");\n        }\n        this.processDefinitionVersion = processDefinitionVersion;\n        return this;\n    }\n\n    @Override\n    public ExecutionQueryImpl processInstanceId(String processInstanceId) {\n        if (processInstanceId == null) {\n            throw new ActivitiIllegalArgumentException(\"Process instance id is null\");\n        }\n        this.processInstanceId = processInstanceId;\n        return this;\n    }\n\n    @Override\n    public ExecutionQuery processInstanceBusinessKey(String businessKey) {\n        if (businessKey == null) {\n            throw new ActivitiIllegalArgumentException(\"Business key is null\");\n        }\n        this.businessKey = businessKey;\n        return this;\n    }\n\n    @Override\n    public ExecutionQuery processInstanceBusinessKey(String processInstanceBusinessKey, boolean includeChildExecutions) {\n        if (!includeChildExecutions) {\n            return processInstanceBusinessKey(processInstanceBusinessKey);\n        } else {\n            if (processInstanceBusinessKey == null) {\n                throw new ActivitiIllegalArgumentException(\"Business key is null\");\n            }\n            this.businessKey = processInstanceBusinessKey;\n            this.includeChildExecutionsWithBusinessKeyQuery = includeChildExecutions;\n            return this;\n        }\n    }","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ExecutionQueryImpl.java#L134-L170","documentation":"ExecutionQueryImpl.processInstanceBusinessKey(String) throws ActivitiIllegalArgumentException when the businessKey argument is null. The filter value must be a concrete non-null string for the query to be built. An empty string is allowed; only null is rejected.","triggerScenarios":"Calling query.processInstanceBusinessKey(businessKey) with a null businessKey, e.g. an unset correlation key from configuration or a null field on a DTO.","commonSituations":"Lookups keyed by a business key (order id, document number) where the key was never assigned; upstream service returned null for the correlation identifier; test code constructing queries with placeholder nulls.","solutions":["Pass a real business key string; check where the key originates and why it is null","Omit the business-key criterion if filtering by it is not intended","Add an explicit null check with a domain-specific error before calling the query API"],"exampleFix":"// before\nList<Execution> execs = runtimeService.createExecutionQuery()\n    .processInstanceBusinessKey(bizKey).list();\n// after\nif (bizKey == null) {\n    throw new IllegalArgumentException(\"businessKey must be provided\");\n}\nList<Execution> execs = runtimeService.createExecutionQuery()\n    .processInstanceBusinessKey(bizKey).list();","handlingStrategy":"validation","validationCode":"if (businessKey != null) { query.processInstanceBusinessKey(businessKey); }","typeGuard":"boolean hasKey = businessKey != null && !businessKey.trim().isEmpty();","tryCatchPattern":"try { q.processInstanceBusinessKey(key); } catch (ActivitiIllegalArgumentException e) { log.error(\"businessKey null: {}\", e.getMessage()); }","preventionTips":["Guarantee business keys are assigned when the process starts","Treat missing correlation keys as domain errors, not silent nulls","Centralize query building in helpers that apply null-filters uniformly"],"tags":["java","activiti","query-builder","null-check"],"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"}