flowable/flowable-engine · error · FlowableIllegalArgumentException

EventRegistryEventDefinition on '" + elementId + "' has an e

Error message

EventRegistryEventDefinition on '" + elementId + "' has an empty eventDefinitionKey; the engine cannot register an event-registry subscription without a key.

What it means

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).

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/parser/handler/EventRegistryEventDefinitionParseHandler.java:71

                startEvent.setBehavior(bpmnParse.getActivityBehaviorFactory()
                        .createEventSubProcessEventRegistryStartEventActivityBehavior(startEvent, key));
            } else {
                startEvent.setBehavior(bpmnParse.getActivityBehaviorFactory()
                        .createEventRegistryStartEventActivityBehavior(startEvent, key, isManualCorrelation(startEvent)));
            }
        }
    }

    protected static boolean isManualCorrelation(StartEvent startEvent) {
        List<ExtensionElement> correlationConfiguration = startEvent.getExtensionElements().get(BpmnXMLConstants.START_EVENT_CORRELATION_CONFIGURATION);
        return correlationConfiguration != null && !correlationConfiguration.isEmpty()
                && BpmnXMLConstants.START_EVENT_CORRELATION_MANUAL.equals(correlationConfiguration.get(0).getElementText());
    }

    private static String requireEventDefinitionKey(EventRegistryEventDefinition eventRegistry, String elementId) {
        String key = eventRegistry.getEventDefinitionKey();
        if (StringUtils.isEmpty(key)) {
            throw new FlowableIllegalArgumentException("EventRegistryEventDefinition on '" + elementId
                    + "' has an empty eventDefinitionKey; the engine cannot register an event-registry subscription without a key.");
        }
        return key;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set the eventKey/eventDefinitionKey attribute on the event-registry event definition in the BPMN XML, e.g. <flowable:eventRegistryEventDefinition eventKey="orderCreated" />
2. If building the model in code, call eventRegistryEventDefinition.setEventDefinitionKey("yourKey") before deployment
3. Verify the event-registry event with that key actually exists in your EventRegistry configuration so deployments correlate correctly

Example fix

<!-- before -->
<startEvent id="start1">
  <extensionElements>
    <flowable:eventRegistryEventDefinition />
  </extensionElements>
</startEvent>

<!-- after -->
<startEvent id="start1">
  <extensionElements>
    <flowable:eventRegistryEventDefinition eventKey="orderCreated" />
  </extensionElements>
</startEvent>

// validate every event-registry start event key before deploying
List<String> problems = new ArrayList<>();
for (StartEvent se : bpmnModel.getMainProcess().findFlowElementsOfType(StartEvent.class)) {
  for (EventDefinition ed : se.getEventDefinitions()) {
    if (ed instanceof EventRegistryEventDefinitionImpl) {
      String key = ((EventRegistryEventDefinitionImpl) ed).getEventDefinitionKey();
      if (key == null || key.trim().isEmpty()) {
        problems.add("startEvent '" + se.getId() + "' missing eventKey");
      }
    }
  }
}
if (!problems.isEmpty()) throw new IllegalArgumentException(problems.toString());

boolean hasEventDefinitionKey(EventRegistryEventDefinition def) {
  return def != null
      && def.getEventDefinitionKey() != null
      && !def.getEventDefinitionKey().trim().isEmpty();
}

try {
  repositoryService.createDeployment().addInputStream("proc.bpmn", xml).deploy();
} catch (FlowableIllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("empty eventDefinitionKey")) {
    logger.error("Fix the BPMN: event-registry event definition needs a non-empty eventKey", e);
  } else {
    throw e;
  }
}

When it happens

Trigger: Deploying a BPMN file containing an event-registry-based start event (e.g. <flowable:eventRegistryEventDefinition>) 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.

Common situations: 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.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• No key set for channel model
• The deployment contains decisions with the same key (decisio
• text is null
• No event definition found for event key ${sendEventServiceTa
• There is no correlation parameter with name '{correlationPar

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/804929a0e78efe5e. Report an issue: GitHub.