{"record":{"id":"804929a0e78efe5e","repo":"flowable/flowable-engine","slug":"eventregistryeventdefinition-on-elementid","errorCode":null,"errorMessage":"EventRegistryEventDefinition on '\" + elementId + \"' has an empty eventDefinitionKey; the engine cannot register an event-registry subscription without a key.","messagePattern":"EventRegistryEventDefinition on '\" \\+ elementId \\+ \"' has an empty eventDefinitionKey; the engine cannot register an event-registry subscription without a key\\.","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/parser/handler/EventRegistryEventDefinitionParseHandler.java","lineNumber":71,"sourceCode":" startEvent.setBehavior(bpmnParse.getActivityBehaviorFactory()\n .createEventSubProcessEventRegistryStartEventActivityBehavior(startEvent, key));\n } else {\n startEvent.setBehavior(bpmnParse.getActivityBehaviorFactory()\n .createEventRegistryStartEventActivityBehavior(startEvent, key, isManualCorrelation(startEvent)));\n }\n }\n }\n\n protected static boolean isManualCorrelation(StartEvent startEvent) {\n List correlationConfiguration = startEvent.getExtensionElements().get(BpmnXMLConstants.START_EVENT_CORRELATION_CONFIGURATION);\n return correlationConfiguration != null && !correlationConfiguration.isEmpty()\n && BpmnXMLConstants.START_EVENT_CORRELATION_MANUAL.equals(correlationConfiguration.get(0).getElementText());\n }\n\n private static String requireEventDefinitionKey(EventRegistryEventDefinition eventRegistry, String elementId) {\n String key = eventRegistry.getEventDefinitionKey();\n if (StringUtils.isEmpty(key)) {\n throw new FlowableIllegalArgumentException(\"EventRegistryEventDefinition on '\" + elementId\n + \"' has an empty eventDefinitionKey; the engine cannot register an event-registry subscription without a key.\");\n }\n return key;\n }\n}\n","sourceCodeStart":53,"sourceCodeEnd":77,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/parser/handler/EventRegistryEventDefinitionParseHandler.java#L53-L77","documentation":"When parsing a BPMN start event that uses an event-registry event definition, the handler builds an EventRegistryEventDefinition and requires a non-empty eventDefinitionKey, which the engine needs to register the subscription in the event registry. The parser deliberately throws FlowableIllegalArgumentException during deployment if the key is missing or empty, refusing to deploy a definition whose in-event correlation cannot be resolved. This is a static BPMN model validation applied at parse time via requireEventDefinitionKey (called by the key() accessor).","triggerScenarios":"Deploying a BPMN file containing an event-registry-based start event (e.g. ) whose eventKey/eventDefinitionKey attribute is absent or set to an empty string; programmatically building the model where EventRegistryEventDefinition.setEventDefinitionKey was never called before parsing/deploying.","commonSituations":"Hand-written or copied BPMN XML missing the eventKey attribute; renaming or deleting an event-registry channel key in the XML without updating the start event; tools generating the model that forget to propagate the key; modeler version mismatches exporting empty attributes.","solutions":["Set the eventKey/eventDefinitionKey attribute on the event-registry event definition in the BPMN XML, e.g. ","If building the model in code, call eventRegistryEventDefinition.setEventDefinitionKey(\"yourKey\") before deployment","Verify the event-registry event with that key actually exists in your EventRegistry configuration so deployments correlate correctly"],"exampleFix":"\n\n \n \n \n\n\n\n\n \n \n \n","handlingStrategy":"validation","validationCode":"// validate every event-registry start event key before deploying\nList problems = new ArrayList<>();\nfor (StartEvent se : bpmnModel.getMainProcess().findFlowElementsOfType(StartEvent.class)) {\n for (EventDefinition ed : se.getEventDefinitions()) {\n if (ed instanceof EventRegistryEventDefinitionImpl) {\n String key = ((EventRegistryEventDefinitionImpl) ed).getEventDefinitionKey();\n if (key == null || key.trim().isEmpty()) {\n problems.add(\"startEvent '\" + se.getId() + \"' missing eventKey\");\n }\n }\n }\n}\nif (!problems.isEmpty()) throw new IllegalArgumentException(problems.toString());","typeGuard":"boolean hasEventDefinitionKey(EventRegistryEventDefinition def) {\n return def != null\n && def.getEventDefinitionKey() != null\n && !def.getEventDefinitionKey().trim().isEmpty();\n}","tryCatchPattern":"try {\n repositoryService.createDeployment().addInputStream(\"proc.bpmn\", xml).deploy();\n} catch (FlowableIllegalArgumentException e) {\n if (e.getMessage() != null && e.getMessage().contains(\"empty eventDefinitionKey\")) {\n logger.error(\"Fix the BPMN: event-registry event definition needs a non-empty eventKey\", e);\n } else {\n throw e;\n }\n}","preventionTips":["Always set eventKey on elements","Use the flowable BPMN modeler/xsd validation so empty required attributes fail locally first","Keep event-registry event keys in sync with your EventRegistry channel definitions","Add a unit test that parses and validates all process resources before deployment"],"tags":["flowable","bpmn","event-registry","validation","deployment"],"backgroundTag":"empty-required-field","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"}