{"record":{"id":"bff26afd1a52a906","repo":"flowable/flowable-engine","slug":"cannot-start-process-instance-by-message-message-bff26a","errorCode":null,"errorMessage":"Cannot start process instance by message: message name is null","messagePattern":"Cannot start process instance by message: message name is null","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceByMessageCmd.java","lineNumber":64,"sourceCode":"        this.messageName = messageName;\r\n        this.businessKey = businessKey;\r\n        this.processVariables = processVariables;\r\n        this.tenantId = tenantId;\r\n    }\r\n\r\n    public StartProcessInstanceByMessageCmd(ProcessInstanceBuilderImpl processInstanceBuilder) {\r\n        this.messageName = processInstanceBuilder.getMessageName();\r\n        this.businessKey = processInstanceBuilder.getBusinessKey();\r\n        this.processVariables = processInstanceBuilder.getVariables();\r\n        this.transientVariables = processInstanceBuilder.getTransientVariables();\r\n        this.tenantId = processInstanceBuilder.getTenantId();\r\n    }\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","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceByMessageCmd.java#L46-L82","documentation":"StartProcessInstanceByMessageCmd throws ActivitiIllegalArgumentException when messageName is null. Starting a process instance by message requires a message name to look up the message start-event subscription; a null name makes the lookup meaningless, so the command fails fast before querying the database.","triggerScenarios":"Calling runtimeService.startProcessInstanceByMessage(null), or message correlation where the name field was never populated.","commonSituations":"Name read from a config/property that was empty; building the correlation request programmatically with a forgotten setMessageName; deserialized correlation object losing its name field.","solutions":["Ensure a non-null message name is supplied: runtimeService.startProcessInstanceByMessage(\"order-received\").","Validate the name at the call site before invoking the API.","Trace where the name variable originates and fix the upstream code or config supplying the empty value."],"exampleFix":"// before\nString name = config.get(\"message.name\");\nruntimeService.startProcessInstanceByMessage(name);\n// after\nString name = config.get(\"message.name\");\nObjects.requireNonNull(name, \"message name must be set\");\nruntimeService.startProcessInstanceByMessage(name);","handlingStrategy":"validation","validationCode":"if (messageName == null || messageName.isEmpty()) {\n    throw new IllegalArgumentException(\"Message name must be provided\");\n}\nruntimeService.startProcessInstanceByMessage(messageName);","typeGuard":"boolean hasMessageName(String s) { return s != null && !s.isEmpty(); }","tryCatchPattern":"try {\n    runtimeService.startProcessInstanceByMessage(messageName);\n} catch (ActivitiIllegalArgumentException e) {\n    logger.error(\"Cannot correlate: message name missing\", e);\n}","preventionTips":["Validate correlation inputs at the application boundary.","Use Objects.requireNonNull on names loaded from config.","Never pass through name fields from unvalidated deserialized objects."],"tags":["message-start-event","null-argument","workflow"],"backgroundTag":"null-argument","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"}