{"record":{"id":"a2e40130f8bae47d","repo":"flowable/flowable-engine","slug":"cannot-start-process-instance-by-message-message","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":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/StartProcessInstanceByMessageCmd.java","lineNumber":84,"sourceCode":"        this(processInstanceBuilder.getMessageName(),\r\n                processInstanceBuilder.getBusinessKey(),\r\n                processInstanceBuilder.getVariables(),\r\n                processInstanceBuilder.getTenantId(),\r\n                processInstanceBuilder.getOwnerId(),\r\n                processInstanceBuilder.getAssigneeId());\r\n        this.transientVariables = processInstanceBuilder.getTransientVariables();\r\n        this.callbackId = processInstanceBuilder.getCallbackId();\r\n        this.callbackType = processInstanceBuilder.getCallbackType();\r\n        this.referenceId = processInstanceBuilder.getReferenceId();\r\n        this.referenceType = processInstanceBuilder.getReferenceType();\r\n        this.businessStatus = processInstanceBuilder.getBusinessStatus();\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 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","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/StartProcessInstanceByMessageCmd.java#L66-L102","documentation":"StartProcessInstanceByMessageCmd validates that a message name was supplied before searching for a message start event subscription. A null name cannot match any subscription, so it fails fast with an IllegalArgumentException.","triggerScenarios":"Calling runtimeService.startProcessInstanceByMessage(null) or startProcessInstanceByMessageAndTenantId(null, tenantId), typically when the message name comes from an unset variable or header.","commonSituations":"A message-driven integration where the message name is read from a config property or header that is missing; programmatic invocation in tests with placeholders.","solutions":["Pass the exact message name declared in the BPMN message start event (the message's name attribute).","Add a null/empty check on the incoming message name before invoking the runtime service.","If the name is external input, validate it in the receiving layer (e.g. reject blank names in the listener)."],"exampleFix":"// before\nString msgName = properties.get(\"messageName\");\nruntimeService.startProcessInstanceByMessage(msgName);\n// after\nString msgName = properties.get(\"messageName\");\nif (msgName == null || msgName.isEmpty()) throw new IllegalArgumentException(\"messageName required\");\nruntimeService.startProcessInstanceByMessage(msgName);","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(messageName, \"messageName must not be null\");\nruntimeService.startProcessInstanceByMessage(messageName);","typeGuard":"boolean hasMessageName(Map<String,Object> msg) { return msg.get(\"messageName\") instanceof String && !((String) msg.get(\"messageName\")).isEmpty(); }","tryCatchPattern":"try {\n    runtimeService.startProcessInstanceByMessage(messageName);\n} catch (FlowableIllegalArgumentException e) {\n    log.error(\"Cannot start process: message name missing\", e);\n}","preventionTips":["Validate message name at the entry point of message-driven integrations","Reference BPMN message names from shared constants to avoid null/unset config values","Reject blank names in listeners before touching the engine API"],"tags":["flowable","message-start-event","null-argument"],"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"}