What causes "Cannot start process instance by message: message name is null" in flowable/flowable-engine?

Ensure a non-null message name is supplied: runtimeService.startProcessInstanceByMessage("order-received").

flowable/flowable-engine · error · ActivitiIllegalArgumentException

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 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.

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.

Example fix

// before
String name = config.get("message.name");
runtimeService.startProcessInstanceByMessage(name);
// after
String name = config.get("message.name");
Objects.requireNonNull(name, "message name must be set");
runtimeService.startProcessInstanceByMessage(name);

Defensive patterns

Strategy: validation

Validate before calling

if (messageName == null || messageName.isEmpty()) {
    throw new IllegalArgumentException("Message name must be provided");
}
runtimeService.startProcessInstanceByMessage(messageName);

Type guard

boolean hasMessageName(String s) { return s != null && !s.isEmpty(); }

Try / catch

try {
    runtimeService.startProcessInstanceByMessage(messageName);
} catch (ActivitiIllegalArgumentException e) {
    logger.error("Cannot correlate: message name missing", e);
}

Prevention

Validate correlation inputs at the application boundary.
Use Objects.requireNonNull on names loaded from config.
Never pass through name fields from unvalidated deserialized objects.

When it happens

Trigger: Calling runtimeService.startProcessInstanceByMessage(null), or message correlation where the name field was never populated.

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

Related errors

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceByMessageCmd.java:64

        this.messageName = messageName;
        this.businessKey = businessKey;
        this.processVariables = processVariables;
        this.tenantId = tenantId;
    }

    public StartProcessInstanceByMessageCmd(ProcessInstanceBuilderImpl processInstanceBuilder) {
        this.messageName = processInstanceBuilder.getMessageName();
        this.businessKey = processInstanceBuilder.getBusinessKey();
        this.processVariables = processInstanceBuilder.getVariables();
        this.transientVariables = processInstanceBuilder.getTransientVariables();
        this.tenantId = processInstanceBuilder.getTenantId();
    }

    @Override
    public ProcessInstance execute(CommandContext commandContext) {

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

        MessageEventSubscriptionEntity messageEventSubscription = commandContext.getEventSubscriptionEntityManager()
                .findMessageStartEventSubscriptionByName(messageName, tenantId);

        if (messageEventSubscription == null) {
            throw new ActivitiObjectNotFoundException("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 ActivitiException("Cannot start process instance by message: subscription to message with name '" + messageName + "' is not a message start event.");
        }

        DeploymentManager deploymentManager = commandContext
                .getProcessEngineConfiguration()
                .getDeploymentManager();

View on GitHub (pinned to d6d39ce1c6)