flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot start process instance by message: message name is…

Error message

Cannot start process instance by message: message name is null

What it means

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.

Solutions

1. Pass the exact message name declared in the BPMN message start event (the message's name attribute).
2. Add a null/empty check on the incoming message name before invoking the runtime service.
3. If the name is external input, validate it in the receiving layer (e.g. reject blank names in the listener).

Example fix

// before
String msgName = properties.get("messageName");
runtimeService.startProcessInstanceByMessage(msgName);
// after
String msgName = properties.get("messageName");
if (msgName == null || msgName.isEmpty()) throw new IllegalArgumentException("messageName required");
runtimeService.startProcessInstanceByMessage(msgName);

Objects.requireNonNull(messageName, "messageName must not be null");
runtimeService.startProcessInstanceByMessage(messageName);

boolean hasMessageName(Map<String,Object> msg) { return msg.get("messageName") instanceof String && !((String) msg.get("messageName")).isEmpty(); }

try {
    runtimeService.startProcessInstanceByMessage(messageName);
} catch (FlowableIllegalArgumentException e) {
    log.error("Cannot start process: message name missing", e);
}

When it happens

Trigger: Calling runtimeService.startProcessInstanceByMessage(null) or startProcessInstanceByMessageAndTenantId(null, tenantId), typically when the message name comes from an unset variable or header.

Common situations: 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.

Related errors

• activatedBefore is null
• activity tenant id is null
• after time is null
• after time is null
• app definition tenantId is null

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/a2e40130f8bae47d. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/StartProcessInstanceByMessageCmd.java:84

        this(processInstanceBuilder.getMessageName(),
                processInstanceBuilder.getBusinessKey(),
                processInstanceBuilder.getVariables(),
                processInstanceBuilder.getTenantId(),
                processInstanceBuilder.getOwnerId(),
                processInstanceBuilder.getAssigneeId());
        this.transientVariables = processInstanceBuilder.getTransientVariables();
        this.callbackId = processInstanceBuilder.getCallbackId();
        this.callbackType = processInstanceBuilder.getCallbackType();
        this.referenceId = processInstanceBuilder.getReferenceId();
        this.referenceType = processInstanceBuilder.getReferenceType();
        this.businessStatus = processInstanceBuilder.getBusinessStatus();
    }

    @Override
    public ProcessInstance execute(CommandContext commandContext) {

        if (messageName == null) {
            throw new FlowableIllegalArgumentException("Cannot start process instance by message: message name is null");
        }

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        MessageEventSubscriptionEntity messageEventSubscription = processEngineConfiguration.getEventSubscriptionServiceConfiguration().getEventSubscriptionService()
                .findMessageStartEventSubscriptionByName(messageName, tenantId);

        if (messageEventSubscription == null) {
            throw new FlowableObjectNotFoundException("Cannot start process instance by message: no subscription to message with name '" + messageName + "' found.", MessageEventSubscriptionEntity.class);
        }

        String processDefinitionId = messageEventSubscription.getConfiguration();
        if (processDefinitionId == null) {
            throw new FlowableException("Cannot start process instance by message: subscription to message with name '" + messageName + "' is not a message start event.");
        }

        DeploymentManager deploymentCache = processEngineConfiguration.getDeploymentManager();

        ProcessDefinition processDefinition = deploymentCache.findDeployedProcessDefinitionById(processDefinitionId);

View on GitHub (pinned to d6d39ce1c6)