{"record":{"id":"2f32c1b8499631a7","repo":"flowable/flowable-engine","slug":"the-process-definition-with-id-processdefinitio","errorCode":null,"errorMessage":"The process definition with id '${processDefinitionId}' does not have an event-registry based start event with a manual subscription behavior.","messagePattern":"The process definition with id '(.+?)' does not have an event-registry based start event with a manual subscription behavior\\.","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/RegisterProcessInstanceStartEventSubscriptionCmd.java","lineNumber":86,"sourceCode":"\n                    // currently, only one event-registry start event is supported for manual subscriptions\n                    if (eventSubscription != null) {\n                        throw new FlowableIllegalArgumentException(\"The process definition with id \" + processDefinition.getId()\n                            + \" has more than one event-registry start events based on manually registered subscriptions, which is currently not supported.\");\n                    }\n\n                    String eventDefinitionKey = eventDefinition.getEventDefinitionKey();\n                    String correlationKey = generateCorrelationConfiguration(eventDefinitionKey, builder.getTenantId(),\n                            builder.getCorrelationParameterValues(), commandContext);\n\n                    eventSubscription = insertEventRegistryEvent(eventDefinitionKey, builder.isDoNotUpdateToLatestVersionAutomatically(), startEvent, processDefinition,\n                        correlationKey, commandContext);\n                }\n            }\n        }\n\n        if (eventSubscription == null) {\n            throw new FlowableIllegalArgumentException(\"The process definition with id '\" + processDefinition.getId()\n                + \"' does not have an event-registry based start event with a manual subscription behavior.\");\n        }\n\n        return eventSubscription;\n    }\n\n    protected EventSubscription insertEventRegistryEvent(String eventDefinitionKey, boolean doNotUpdateToLatestVersionAutomatically, StartEvent startEvent,\n            ProcessDefinition processDefinition, String correlationKey, CommandContext commandContext) {\n        \n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n        EventSubscriptionService eventSubscriptionService = processEngineConfiguration.getEventSubscriptionServiceConfiguration().getEventSubscriptionService();\n        EventSubscriptionBuilder eventSubscriptionBuilder = eventSubscriptionService.createEventSubscriptionBuilder()\n                .eventType(eventDefinitionKey)\n                .activityId(startEvent.getId())\n                .processDefinitionId(processDefinition.getId())\n                .scopeType(ScopeTypes.BPMN)\n                .configuration(correlationKey);\n","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/RegisterProcessInstanceStartEventSubscriptionCmd.java#L68-L104","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Edit the BPMN XML so the start event is an event-registry start event with flowable:eventSubscriptionBehavior=\"manual\" and redeploy the process definition.","Verify the processDefinitionId you pass refers to the definition version containing the manual event-registry start event (use repositoryService.getProcessModel / inspect the deployed model).","Check the correlationKey matches the event key defined on the start event's event-registry subscription.","If you expect the subscription to exist at runtime, confirm the EventRegistry was configured and the inbound event/subscription was created before correlating."],"exampleFix":"// before: correlate against a definition without a manual event-registry start event\nruntimeService.createProcessInstanceStartEventSubscriptionBuilder()\n    .processDefinitionId(processDefinitionId)\n    .correlationKey(\"myCorrelationKey\")\n    .correlate();\n// after: deploy a BPMN with <bpmn:startEvent id=\"start\" flowable:eventSubscriptionBehavior=\"manual\">\n//   <bpmn:extensionElements>\n//     <flowable:eventRegistryEventDefinition eventKey=\"myEventKey\" />\n//   </bpmn:extensionElements>\n// </bpmn:startEvent>\nruntimeService.createProcessInstanceStartEventSubscriptionBuilder()\n    .processDefinitionId(updatedDefinitionId) // id of the redeployed definition\n    .correlationKey(\"myEventKey\")\n    .correlate();","handlingStrategy":"validation","validationCode":"String bpmnXml = repositoryService.getProcessModel(processDefinitionId).toString(); // or inspect the model\nboolean hasManualEventStart = bpmnXml.contains(\"eventSubscriptionBehavior=\\\"manual\\\"\");\nif (!hasManualEventStart) {\n    throw new IllegalStateException(\"Definition \" + processDefinitionId + \" has no manual event-registry start event\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.createProcessInstanceStartEventSubscriptionBuilder()\n        .processDefinitionId(processDefinitionId)\n        .correlationKey(key)\n        .correlate();\n} catch (FlowableIllegalArgumentException e) {\n    // definition lacks manual event-registry start subscription; redeploy corrected BPMN or route differently\n}","preventionTips":["Always model event-registry start events with flowable:eventSubscriptionBehavior=\"manual\" when using the start-event subscription API.","After deploying, assert the definition contains the expected start event before correlating.","Keep correlationKeys in sync with the event keys defined in the deployed BPMN."],"tags":["flowable","event-registry","process-definition","start-event-subscription"],"backgroundTag":"resource-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}