{"record":{"id":"a58a641516ff40be","repo":"flowable/flowable-engine","slug":"cannot-start-process-instance-by-message-subscrip-a58a64","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 '<messageName>' is not a message start event\\.","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceByMessageCmd.java","lineNumber":76,"sourceCode":"    }\r\n\r\n    @Override\r\n    public ProcessInstance execute(CommandContext commandContext) {\r\n\r\n        if (messageName == null) {\r\n            throw new ActivitiIllegalArgumentException(\"Cannot start process instance by message: message name is null\");\r\n        }\r\n\r\n        MessageEventSubscriptionEntity messageEventSubscription = commandContext.getEventSubscriptionEntityManager()\r\n                .findMessageStartEventSubscriptionByName(messageName, tenantId);\r\n\r\n        if (messageEventSubscription == null) {\r\n            throw new ActivitiObjectNotFoundException(\"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 ActivitiException(\"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 deploymentManager = commandContext\r\n                .getProcessEngineConfiguration()\r\n                .getDeploymentManager();\r\n\r\n        ProcessDefinitionEntity processDefinition = (ProcessDefinitionEntity) deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);\r\n        if (processDefinition == null) {\r\n            throw new ActivitiObjectNotFoundException(\"No process definition found for id '\" + processDefinitionId + \"'\", ProcessDefinition.class);\r\n        }\r\n\r\n        // Do not start process a process instance if the process definition is suspended\r\n        if (deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {\r\n            throw new ActivitiException(\"Cannot start process instance. Process definition \"\r\n                    + processDefinition.getName() + \" (id = \" + processDefinition.getId() + \") is suspended\");\r\n        }\r\n\r\n        ActivityImpl startActivity = processDefinition.findActivity(messageEventSubscription.getActivityId());\r","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceByMessageCmd.java#L58-L94","documentation":"StartProcessInstanceByMessageCmd throws ActivitiException when the message start-event subscription found for the message name has a null configuration, meaning its processDefinitionId could not be resolved. A valid message start subscription must point at a deployed process definition; a dangling subscription indicates corrupted or incompletely deployed state, so the command aborts.","triggerScenarios":"Correlating a message whose start-event subscription row in ACT_RU_EVENT_SUBSCRIPTION has CONFIGURATION_ null — typically after a partial/broken deployment or manual data manipulation.","commonSituations":"Deployment deleted while subscriptions leaked; database migration between engine versions leaving stale rows; manual SQL cleanup removing process definition rows but not event subscriptions.","solutions":["Redeploy the process definition containing the message start event so the subscription is recreated with a valid configuration.","Clean orphaned subscriptions in ACT_RU_EVENT_SUBSCRIPTION (message-type rows with CONFIGURATION_ IS NULL) after backing up the DB.","Check deployment integrity with repositoryService.createDeploymentQuery() and verify the definition exists before correlating."],"exampleFix":"// before\nruntimeService.startProcessInstanceByMessage(\"OrderReceived\");\n// after\nList<EventSubscription> subs = repositoryService.createEventSubscriptionQuery().eventName(\"OrderReceived\").list();\nif (subs.isEmpty()) {\n    throw new IllegalStateException(\"No message start subscription deployed for OrderReceived\");\n}\nruntimeService.startProcessInstanceByMessage(\"OrderReceived\");","handlingStrategy":"validation","validationCode":"List<EventSubscription> subs = repositoryService.createEventSubscriptionQuery().eventName(messageName).list();\nboolean healthy = !subs.isEmpty() && subs.get(0).getConfiguration() != null;","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.startProcessInstanceByMessage(messageName);\n} catch (ActivitiException e) {\n    logger.error(\"Corrupt message subscription for '{}' — redeploy required\", messageName, e);\n}","preventionTips":["Never manipulate ACT_RU_EVENT_SUBSCRIPTION or definition tables with manual SQL.","Verify deployment integrity after DB restores or engine-version migrations.","Keep deletes of definitions and subscriptions atomic (cascade)."],"tags":["message-start-event","corrupt-state","deployment","workflow"],"backgroundTag":"internal-invariant-violation","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"}