flowable/flowable-engine · error · FlowableIllegalArgumentException

The process definition with id '${processDefinitionId}' does

Error message

The process definition with id '${processDefinitionId}' does not have an event-registry based start event with a manual subscription behavior.

What it means

Flowable throws this when registering a process instance start event subscription against a process definition that has no event-registry based start event with 'manual' subscription behavior. RegisterProcessInstanceStartEventSubscriptionCmd looks up an eligible event subscription for the given correlation key and definition; if none exists, it fails fast with FlowableIllegalArgumentException. The definition exists, but it simply is not wired for manual event-registry start subscriptions.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/RegisterProcessInstanceStartEventSubscriptionCmd.java:86

                    // currently, only one event-registry start event is supported for manual subscriptions
                    if (eventSubscription != null) {
                        throw new FlowableIllegalArgumentException("The process definition with id " + processDefinition.getId()
                            + " has more than one event-registry start events based on manually registered subscriptions, which is currently not supported.");
                    }

                    String eventDefinitionKey = eventDefinition.getEventDefinitionKey();
                    String correlationKey = generateCorrelationConfiguration(eventDefinitionKey, builder.getTenantId(),
                            builder.getCorrelationParameterValues(), commandContext);

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

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

        return eventSubscription;
    }

    protected EventSubscription insertEventRegistryEvent(String eventDefinitionKey, boolean doNotUpdateToLatestVersionAutomatically, StartEvent startEvent,
            ProcessDefinition processDefinition, String correlationKey, CommandContext commandContext) {
        
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        EventSubscriptionService eventSubscriptionService = processEngineConfiguration.getEventSubscriptionServiceConfiguration().getEventSubscriptionService();
        EventSubscriptionBuilder eventSubscriptionBuilder = eventSubscriptionService.createEventSubscriptionBuilder()
                .eventType(eventDefinitionKey)
                .activityId(startEvent.getId())
                .processDefinitionId(processDefinition.getId())
                .scopeType(ScopeTypes.BPMN)
                .configuration(correlationKey);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Edit the BPMN XML so the start event is an event-registry start event with flowable:eventSubscriptionBehavior="manual" and redeploy the process definition.
2. Verify the processDefinitionId you pass refers to the definition version containing the manual event-registry start event (use repositoryService.getProcessModel / inspect the deployed model).
3. Check the correlationKey matches the event key defined on the start event's event-registry subscription.
4. If you expect the subscription to exist at runtime, confirm the EventRegistry was configured and the inbound event/subscription was created before correlating.

Example fix

// before: correlate against a definition without a manual event-registry start event
runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
    .processDefinitionId(processDefinitionId)
    .correlationKey("myCorrelationKey")
    .correlate();
// after: deploy a BPMN with <bpmn:startEvent id="start" flowable:eventSubscriptionBehavior="manual">
//   <bpmn:extensionElements>
//     <flowable:eventRegistryEventDefinition eventKey="myEventKey" />
//   </bpmn:extensionElements>
// </bpmn:startEvent>
runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
    .processDefinitionId(updatedDefinitionId) // id of the redeployed definition
    .correlationKey("myEventKey")
    .correlate();

String bpmnXml = repositoryService.getProcessModel(processDefinitionId).toString(); // or inspect the model
boolean hasManualEventStart = bpmnXml.contains("eventSubscriptionBehavior=\"manual\"");
if (!hasManualEventStart) {
    throw new IllegalStateException("Definition " + processDefinitionId + " has no manual event-registry start event");
}

try {
    runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
        .processDefinitionId(processDefinitionId)
        .correlationKey(key)
        .correlate();
} catch (FlowableIllegalArgumentException e) {
    // definition lacks manual event-registry start subscription; redeploy corrected BPMN or route differently
}

When it happens

Trigger: Calling runtimeService.createProcessInstanceStartEventSubscriptionBuilder()...correlate/correlateStart() (the RegisterProcessInstanceStartEventSubscriptionCmd.execute path) with a processDefinitionId whose BPMN start event is not an event-registry start event with flowable:eventSubscriptionBehavior="manual", or with a correlationKey that matches no such subscription on that definition.

Common situations: Developers migrate from message/signal start events to event-registry start events and assume any start event works; the BPMN model uses automatic/conditional subscription behavior instead of manual; the correlationKey string does not match the start event's event key; deploying an older definition version that lacks the manual-subscription start event and passing its id.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• No process definition found for name:
• Cannot find case definition with id
• Process definition category is null
• Process definition name is null
• category is null

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