What causes "An event definition key is mandatory" in flowable/flowable-engine?

Set the key on the builder: .key("orderCreated") before build/deploy

flowable/flowable-engine · error · FlowableIllegalArgumentException

An event definition key is mandatory

Error message

An event definition key is mandatory

What it means

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.

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

Example fix

// before
EventModel model = eventRepositoryService.createEventModelBuilder()
    .payload("customerId", "string")
    .createEventModel();
// after
EventModel model = eventRepositoryService.createEventModelBuilder()
    .key("orderCreated")
    .payload("customerId", "string")
    .createEventModel();

Defensive patterns

Strategy: validation

Validate before calling

if (key == null || key.trim().isEmpty()) {
    throw new IllegalArgumentException("Event model key is required");
}

Try / catch

try {
    EventModel model = builder.createEventModel();
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("key is mandatory")) { /* set key and rebuild */ }
}

Prevention

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

When it happens

Trigger: Calling createEventModel()/eventModel() (or deploy()) on an EventModelBuilder where key was never set or was set to an empty string.

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

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/model/EventModelBuilderImpl.java:151

        
        EventModel eventModel = buildEventModel();

        return eventRepository.createDeployment()
            .name(deploymentName)
            .addEventDefinition(resourceName, eventJsonConverter.convertToJson(eventModel))
            .category(category)
            .parentDeploymentId(parentDeploymentId)
            .tenantId(deploymentTenantId)
            .deploy();
    }

    protected EventModel buildEventModel() {
        EventModel eventModel = new EventModel();

        if (StringUtils.isNotEmpty(key)) {
            eventModel.setKey(key);
        } else {
            throw new FlowableIllegalArgumentException("An event definition key is mandatory");
        }

        eventModel.setPayload(eventPayloadDefinitions.values());

        return eventModel;
    }
}

View on GitHub (pinned to d6d39ce1c6)