flowable/flowable-engine · error · FlowableIllegalArgumentException

Either eventDefinitionId or eventDefinitionKey is required.

Error message

Either eventDefinitionId or eventDefinitionKey is required.

What it means

REST request validation in EventInstanceCollectionResource.validateRequestParameters: the create-event-instance body carries neither eventDefinitionId nor eventDefinitionKey, so the engine cannot determine which event definition the instance belongs to.

Solutions

Set either eventDefinitionId or eventDefinitionKey in the request body.
Verify JSON field names match EventInstanceCreateRequest properties exactly.
Validate the body client-side before sending.
Catch FlowableIllegalArgumentException and return a 400 with guidance.

Example fix

// before
{ "channelDefinitionKey": "ch", "eventPayload": {} }
// after
{ "eventDefinitionKey": "myEvent", "channelDefinitionKey": "ch", "eventPayload": {} }

Defensive patterns

Strategy: validation

Validate before calling

if (req.getEventDefinitionId() == null && req.getEventDefinitionKey() == null) {
    throw new IllegalArgumentException("Set eventDefinitionId or eventDefinitionKey");
}

Type guard

null

Try / catch

try {
    createEventInstance(req);
} catch (FlowableIllegalArgumentException e) {
    logger.error("Invalid event instance request: {}", e.getMessage());
}

Prevention

Always set exactly one of eventDefinitionId/eventDefinitionKey
Match JSON property names to the request class
Validate request bodies before sending

When it happens

Trigger: POSTing an EventInstanceCreateRequest JSON body with an empty payload for both eventDefinitionId and eventDefinitionKey fields.

Common situations: Omitting the fields from the JSON body; field-name typos that deserialize to null; building the request programmatically without setting either field.

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/3c34fbda5443f2d6. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-event-registry-rest/src/main/java/org/flowable/eventregistry/rest/service/api/runtime/EventInstanceCollectionResource.java:122

        if (eventDefinition == null) {
            throw new FlowableObjectNotFoundException("No event definition found");
        }

        ChannelModel channelModel = null;
        if (StringUtils.isNotEmpty(request.getChannelDefinitionId())) {
            channelModel = repositoryService.getChannelModelById(request.getChannelDefinitionId());
        } else if (StringUtils.isNotEmpty(request.getTenantId())) {
            channelModel = repositoryService.getChannelModelByKey(request.getChannelDefinitionKey(), request.getTenantId());
        } else {
            channelModel = repositoryService.getChannelModelByKey(request.getChannelDefinitionKey());
        }

        eventRegistry.eventReceived((InboundChannelModel) channelModel, request.getEventPayload().toString());
    }

    protected void validateRequestParameters(@RequestBody EventInstanceCreateRequest request) {
        if (request.getEventDefinitionId() == null && request.getEventDefinitionKey() == null) {
            throw new FlowableIllegalArgumentException("Either eventDefinitionId or eventDefinitionKey is required.");
        }

        int paramsSet = ((request.getEventDefinitionId() != null) ? 1 : 0) + ((request.getEventDefinitionKey() != null) ? 1 : 0);
        if (paramsSet > 1) {
            throw new FlowableIllegalArgumentException("Only one of eventDefinitionId or eventDefinitionKey should be set.");
        }

        if (request.getChannelDefinitionId() == null && request.getChannelDefinitionKey() == null) {
            throw new FlowableIllegalArgumentException("Either channelDefinitionId or channelDefinitionKey is required.");
        }

        paramsSet = ((request.getChannelDefinitionId() != null) ? 1 : 0) + ((request.getChannelDefinitionKey() != null) ? 1 : 0);
        if (paramsSet > 1) {
            throw new FlowableIllegalArgumentException("Only one of eventDefinitionId or eventDefinitionKey should be set.");
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)