{"record":{"id":"c3106aeb43b4d368","repo":"flowable/flowable-engine","slug":"key-is-null-c3106a","errorCode":null,"errorMessage":"key is null","messagePattern":"key is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessDefinitionQueryImpl.java","lineNumber":184,"sourceCode":"            throw new FlowableIllegalArgumentException(\"ids are null\");\n        }\n        this.deploymentIds = deploymentIds;\n        return this;\n    }\n\n    @Override\n    public ProcessDefinitionQueryImpl parentDeploymentId(String parentDeploymentId) {\n        if (parentDeploymentId == null) {\n            throw new FlowableIllegalArgumentException(\"parentDeploymentId is null\");\n        }\n        this.parentDeploymentId = parentDeploymentId;\n        return this;\n    }\n\n    @Override\n    public ProcessDefinitionQueryImpl processDefinitionKey(String key) {\n        if (key == null) {\n            throw new FlowableIllegalArgumentException(\"key is null\");\n        }\n        this.key = key;\n        return this;\n    }\n\n    @Override\n    public ProcessDefinitionQueryImpl processDefinitionKeyLike(String keyLike) {\n        if (keyLike == null) {\n            throw new FlowableIllegalArgumentException(\"keyLike is null\");\n        }\n        this.keyLike = keyLike;\n        return this;\n    }\n\n    @Override\n    public ProcessDefinitionQueryImpl processDefinitionResourceName(String resourceName) {\n        if (resourceName == null) {\n            throw new FlowableIllegalArgumentException(\"resourceName is null\");","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessDefinitionQueryImpl.java#L166-L202","documentation":"Flowable throws FlowableIllegalArgumentException with message \"key is null\" when processDefinitionKey(null) is called. The key identifies the process definition (e.g. 'orderProcess'), so it is a mandatory non-null filter. Internal Flowable code paths such as alreadyExistingProcessDefinitions and findNewLatestProcessDefinitionAfterRemovalOf also rely on this method and expect a real key.","triggerScenarios":"Calling query.processDefinitionKey(key) with null key; passing a null key extracted from a ProcessDefinition entity; BPMN deployment tooling calling it without a parsed key.","commonSituations":"Starting processes by key where the key comes from an unresolved config property or message header; tests asserting on definitions where the process id in the BPMN XML was renamed so the stored key lookup yields null; version-upgrade scripts.","solutions":["Pass the actual definition key string, e.g. processDefinitionKey(\"orderProcess\").","Check the variable for null before the call and fail with a domain-specific message.","If the key comes from a BPMN file, validate the <process id=...> attribute is present and non-empty before deploying/querying."],"exampleFix":"// before\nString key = message.getHeader(\"processKey\"); // may be null\nruntimeService.startProcessInstanceByKey(key);\n// (and earlier) query.processDefinitionKey(key);\n// after\nString key = message.getHeader(\"processKey\");\nif (key == null) {\n    throw new IllegalArgumentException(\"processKey header is required\");\n}\nruntimeService.startProcessInstanceByKey(key);\nquery.processDefinitionKey(key);","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(key, \"process definition key is required\");\nquery.processDefinitionKey(key);","typeGuard":"boolean isValidKey(String key) { return key != null && key.matches(\"[a-zA-Z_][a-zA-Z0-9_]*\"); }","tryCatchPattern":"try {\n    query.processDefinitionKey(key);\n} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"A non-null process definition key is required\");\n}","preventionTips":["Store process keys as constants/enums instead of ad-hoc strings","Validate that BPMN <process id> attributes are present before deploying","Check message/header extraction for null before starting processes or querying by key"],"tags":["flowable","null-argument","query-builder","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-18T11:17:12.947Z"}