flowable/flowable-engine · error · FlowableIllegalArgumentException

Either channelDefinitionId or channelDefinitionKey is…

Error message

Either channelDefinitionId or channelDefinitionKey is required.

What it means

REST request validation in EventInstanceCollectionResource.validateRequestParameters: the request identified an event definition but supplied neither channelDefinitionId nor channelDefinitionKey, so the inbound channel through which to fire the event cannot be resolved.

Solutions

Add channelDefinitionId or channelDefinitionKey to the request body.
Verify JSON property names match EventInstanceCreateRequest.
Confirm the channel model is deployed and its id/key is correct.
Validate request body client-side before calling the endpoint.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if (req.getChannelDefinitionId() == null && req.getChannelDefinitionKey() == null) {
    throw new IllegalArgumentException("Set channelDefinitionId or channelDefinitionKey");
}

Type guard

null

Try / catch

try {
    createEventInstance(req);
} catch (FlowableIllegalArgumentException e) {
    logger.error("Missing channel definition in request", e);
}

Prevention

Always include channel identification in event payloads
Source channel ids from deployed channel model config
Validate the body shape against the API model

When it happens

Trigger: POST body with event definition set but both channelDefinitionId and channelDefinitionKey null/missing.

Common situations: Forgetting channel fields in the JSON payload; typos in channel property names; building requests from partial configuration where channel info is absent.

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/4c6d485569c32822. 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:131

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