flowable/flowable-engine · error · FlowableIllegalArgumentException

The case definition with id

Error message

The case definition with id 

What it means

Thrown as FlowableIllegalArgumentException when registering a start-event subscription for a case definition that has no event-registry based start event with 'manual' subscription behavior, so the resolved eventSubscription ends up null. The command requires an event-registry start event configured with EventSubscriptionServiceBehavior.MANUAL.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/RegisterCaseInstanceStartEventSubscriptionCmd.java:65

    @Override
    public EventSubscription execute(CommandContext commandContext) {
        CaseDefinition caseDefinition = getLatestCaseDefinitionByKey(builder.getCaseDefinitionKey(), builder.getTenantId(), commandContext);
        Case caze = getCase(caseDefinition.getId(), commandContext);

        EventSubscription eventSubscription = null;
        String eventDefinitionKey = caze.getStartEventType();
        String startCorrelationConfiguration = getStartCorrelationConfiguration(caseDefinition.getId(), commandContext);

        if (eventDefinitionKey != null && Objects.equals(startCorrelationConfiguration, CmmnXmlConstants.START_EVENT_CORRELATION_MANUAL)) {
            String correlationKey = generateCorrelationConfiguration(eventDefinitionKey, builder.getTenantId(), builder.getCorrelationParameterValues(), commandContext);

            eventSubscription = insertEventRegistryEvent(eventDefinitionKey, builder.isDoNotUpdateToLatestVersionAutomatically(), caseDefinition,
                correlationKey, commandContext);
        }

        if (eventSubscription == null) {
            throw new FlowableIllegalArgumentException("The case definition with id '" + caseDefinition.getId()
                + "' does not have an event-registry based start event with a manual subscription behavior.");
        }

        return eventSubscription;
    }

    protected EventSubscription insertEventRegistryEvent(String eventDefinitionKey, boolean doNotUpdateToLatestVersionAutomatically,
        CaseDefinition caseDefinition, String correlationKey, CommandContext commandContext) {
        
        CmmnEngineConfiguration caseEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        EventSubscriptionService eventSubscriptionService = caseEngineConfiguration.getEventSubscriptionServiceConfiguration().getEventSubscriptionService();
        EventSubscriptionBuilder eventSubscriptionBuilder = eventSubscriptionService.createEventSubscriptionBuilder()
                .eventType(eventDefinitionKey)
                .scopeDefinitionId(caseDefinition.getId())
                .scopeType(ScopeTypes.CMMN)
                .configuration(correlationKey);

        if (caseDefinition.getTenantId() != null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Confirm the case definition's start event is an event-registry start event with flowable:eventSubscriptionServiceBehavior="manual" in the CMMN XML
2. Point the builder at the correct case definition id that actually contains the manual event start event
3. If automatic subscription is intended, rely on automatic subscription instead of the manual registration command

Example fix

// before
<startEvent id="start">
  <extensionElements>
    <flowable:eventRegistryEventDefinition eventDefinitionKey="orderArrived" />
  </extensionElements>
</startEvent>
// after
<flowable:eventRegistryEventDefinition eventDefinitionKey="orderArrived"
    flowable:eventSubscriptionServiceBehavior="manual" />

// ensure the start event is event-registry based with manual behavior in the CMMN XML
// <flowable:eventRegistryEventDefinition eventDefinitionKey="..." eventSubscriptionServiceBehavior="manual"/>

try { runtimeService.registerCaseInstanceStartEventSubscription(...); }
catch (FlowableIllegalArgumentException e) { /* case definition lacks manual event-registry start event */ }

When it happens

Trigger: Calling CmmnRuntimeService.createCaseInstanceStartEventSubscriptionBuilder(...) / registerCaseInstanceStartEventSubscription for a case definition whose start event either is not event-registry based or has a different (non-manual) subscription behavior.

Common situations: Misconfigured CMMN: start event missing the event-registry binding; subscription behavior set to automatic/default instead of manual; passing the wrong case definition that has no event start event at all.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Could not find an implementation of the org.flowable.cdi.imp
• no SMTP host is configured for the default mail server
• no SMTP host is configured for the mail server for tenant {t
• The mail client provider is not an instance of DefaultMailCl
• couldn't initialize cmmn engine from spring configuration re

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