{"record":{"id":"26e60c8f1acd0431","repo":"flowable/flowable-engine","slug":"cannot-start-process-instance-by-message-subscrip","errorCode":null,"errorMessage":"Cannot start process instance by message: subscription to message with name '${messageName}' is not a message start event.","messagePattern":"Cannot start process instance by message: subscription to message with name '(.+?)' is not a message start event\\.","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/StartProcessInstanceByMessageCmd.java","lineNumber":97,"sourceCode":"\r\n    @Override\r\n    public ProcessInstance execute(CommandContext commandContext) {\r\n\r\n        if (messageName == null) {\r\n            throw new FlowableIllegalArgumentException(\"Cannot start process instance by message: message name is null\");\r\n        }\r\n\r\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\r\n        MessageEventSubscriptionEntity messageEventSubscription = processEngineConfiguration.getEventSubscriptionServiceConfiguration().getEventSubscriptionService()\r\n                .findMessageStartEventSubscriptionByName(messageName, tenantId);\r\n\r\n        if (messageEventSubscription == null) {\r\n            throw new FlowableObjectNotFoundException(\"Cannot start process instance by message: no subscription to message with name '\" + messageName + \"' found.\", MessageEventSubscriptionEntity.class);\r\n        }\r\n\r\n        String processDefinitionId = messageEventSubscription.getConfiguration();\r\n        if (processDefinitionId == null) {\r\n            throw new FlowableException(\"Cannot start process instance by message: subscription to message with name '\" + messageName + \"' is not a message start event.\");\r\n        }\r\n\r\n        DeploymentManager deploymentCache = processEngineConfiguration.getDeploymentManager();\r\n\r\n        ProcessDefinition processDefinition = deploymentCache.findDeployedProcessDefinitionById(processDefinitionId);\r\n        if (processDefinition == null) {\r\n            throw new FlowableObjectNotFoundException(\"No process definition found for id '\" + processDefinitionId + \"'\", ProcessDefinition.class);\r\n        }\r\n\r\n        ProcessInstanceHelper processInstanceHelper = processEngineConfiguration.getProcessInstanceHelper();\r\n        ProcessInstance processInstance = processInstanceHelper.createAndStartProcessInstanceByMessage(processDefinition,\r\n                messageName, businessKey, businessStatus, processVariables, transientVariables, callbackId, callbackType, referenceId, referenceType,\r\n                ownerId, assigneeId);\r\n\r\n        return processInstance;\r\n    }\r\n\r\n}\r","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/StartProcessInstanceByMessageCmd.java#L79-L115","documentation":"Flowable throws this when a message event subscription exists for the given message name, but its configuration does not point to a process definition — i.e. the subscription is not a message start event of a top-level process. StartProcessInstanceByMessageCmd can only start a process instance from a message start event; intermediate message catches or other subscription types are rejected.","triggerScenarios":"Calling RuntimeService.startProcessInstanceByMessage(messageName, ...) when the subscription found for messageName belongs to a non-start event (e.g. an intermediate catch message event or boundary event), so messageEventSubscription.getConfiguration() returns null.","commonSituations":"The BPMN XML declares the message only on an intermediate catch or boundary event instead of a <startEvent><messageEventDefinition>; a typo makes the API match a wrong subscription type; the process was re-deployed and the start-event subscription was replaced.","solutions":["Declare the message on a message start event in the BPMN XML: <startEvent><messageEventDefinition messageRef=\"...\"/></startEvent>","Verify the messageName passed to startProcessInstanceByMessage exactly matches the message start event's message name","Check that the latest deployment actually contains the message start event subscription","If the message targets an intermediate/boundary event, use RuntimeService.messageEventReceived(...) or execution.trigger instead"],"exampleFix":"// before (BPMN): message only on intermediate catch\ncatchEvent id=\"wait\" messageRef=\"orderMsg\"\n// after (BPMN): message on start event\n<startEvent id=\"start\"><messageEventDefinition messageRef=\"orderMsg\"/></startEvent>","handlingStrategy":"validation","validationCode":"MessageEventSubscription sub = runtimeService.createEventSubscriptionQuery()\n    .messageEventSubscriptionName(\"orderMsg\").singleResult();\nif (sub == null || !runtimeService.createProcessDefinitionQuery()\n        .processDefinitionKey(\"orderProcess\").count() > 0) {\n    throw new IllegalStateException(\"message start event not deployed for orderMsg\");\n}","typeGuard":"boolean hasMessageStartEvent(RuntimeService rs, String msg) {\n    return rs.createEventSubscriptionQuery().messageEventSubscriptionName(msg).singleResult() != null;\n}","tryCatchPattern":"try {\n    runtimeService.startProcessInstanceByMessage(\"orderMsg\");\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"not a message start event\")) { /* fix BPMN / use messageEventReceived */ }\n    throw e;\n}","preventionTips":["Always declare process-start messages on a <startEvent><messageEventDefinition>","Unit-test message start by attempting the start in an integration test after deployment","Keep message names in constants shared between BPMN XML and Java code"],"tags":["bpmn","process-start","message-event","configuration"],"backgroundTag":"invalid-state-transition","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}