{"record":{"id":"3ffe2db5b7c6ed4a","repo":"flowable/flowable-engine","slug":"an-event-definition-key-is-mandatory","errorCode":null,"errorMessage":"An event definition key is mandatory","messagePattern":"An event definition key is mandatory","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/model/EventModelBuilderImpl.java","lineNumber":151,"sourceCode":"        \n        EventModel eventModel = buildEventModel();\n\n        return eventRepository.createDeployment()\n            .name(deploymentName)\n            .addEventDefinition(resourceName, eventJsonConverter.convertToJson(eventModel))\n            .category(category)\n            .parentDeploymentId(parentDeploymentId)\n            .tenantId(deploymentTenantId)\n            .deploy();\n    }\n\n    protected EventModel buildEventModel() {\n        EventModel eventModel = new EventModel();\n\n        if (StringUtils.isNotEmpty(key)) {\n            eventModel.setKey(key);\n        } else {\n            throw new FlowableIllegalArgumentException(\"An event definition key is mandatory\");\n        }\n\n        eventModel.setPayload(eventPayloadDefinitions.values());\n\n        return eventModel;\n    }\n}\n","sourceCodeStart":133,"sourceCodeEnd":159,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/model/EventModelBuilderImpl.java#L133-L159","documentation":"buildEventModel assembles the in-memory EventModel from builder state and requires a non-empty key, because the key is the primary identifier for the event definition across deployments and runtime lookups. If the key is missing or empty, Flowable throws this FlowableIllegalArgumentException.","triggerScenarios":"Calling createEventModel()/eventModel() (or deploy()) on an EventModelBuilder where key was never set or was set to an empty string.","commonSituations":"Programmatic event model construction without .key(...); parsing JSON event files whose top-level 'key' field is missing (when the builder derives key from parsed JSON); copy-pasted builder code that renamed the event but left key blank.","solutions":["Set the key on the builder: .key(\"orderCreated\") before build/deploy","If building from JSON, ensure the JSON contains a non-empty top-level 'key' field","Validate builder state (key present) before calling buildEventModel in wrapper code"],"exampleFix":"// before\nEventModel model = eventRepositoryService.createEventModelBuilder()\n    .payload(\"customerId\", \"string\")\n    .createEventModel();\n// after\nEventModel model = eventRepositoryService.createEventModelBuilder()\n    .key(\"orderCreated\")\n    .payload(\"customerId\", \"string\")\n    .createEventModel();","handlingStrategy":"validation","validationCode":"if (key == null || key.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"Event model key is required\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    EventModel model = builder.createEventModel();\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"key is mandatory\")) { /* set key and rebuild */ }\n}","preventionTips":["Always set .key(...) immediately after createEventModelBuilder()","Validate event JSON files contain a top-level non-empty 'key' before deployment","Centralize event model creation so key setting is mandatory in one place"],"tags":["flowable","event-registry","builder","validation"],"backgroundTag":"missing-required-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"}