flowable/flowable-engine · error · ActivitiObjectNotFoundException

Cannot start process instance by message: no subscription…

Error message

Cannot start process instance by message: no subscription to message with name '<messageName>' found.

What it means

StartProcessInstanceByMessageCmd throws ActivitiObjectNotFoundException when no message start-event subscription exists with the given message name (within the optional tenant scope). The engine correlates the message to a deployed process definition's message start event; absent such a subscription, no instance can be started, and it fails with MessageEventSubscriptionEntity.class as the missing type.

Solutions

1. Verify the subscription: runtimeService.createEventSubscriptionQuery().eventType("message").eventName(messageName).list() should be non-empty.
2. Align the message name with the exact name in the BPMN file and redeploy if the model changed.
3. Pass the correct tenantId (or none for the default tenant) matching the deployment.

Example fix

// before
runtimeService.startProcessInstanceByMessage("OrderReceived", "tenant-42");
// after
if (!runtimeService.createEventSubscriptionQuery().eventName("OrderReceived").tenantId("tenant-42").list().isEmpty()) {
    runtimeService.startProcessInstanceByMessage("OrderReceived", "tenant-42");
}

boolean hasStartSubscription = !repositoryService.createEventSubscriptionQuery()
        .eventName(messageName).tenantId(tenantId).list().isEmpty();
if (hasStartSubscription) runtimeService.startProcessInstanceByMessage(messageName, tenantId);

try {
    runtimeService.startProcessInstanceByMessage(messageName, tenantId);
} catch (ActivitiObjectNotFoundException e) {
    logger.warn("No message start event '{}' for tenant {}", messageName, tenantId, e);
}

When it happens

Trigger: Calling runtimeService.startProcessInstanceByMessage(messageName[, tenantId]) where no deployed process definition has a message start event subscribed to that name, or the tenantId does not match the subscription's tenant.

Common situations: BPMN model lacks a message start event (or it was removed in the latest deployment); message name differs from the bpmn:message name; wrong tenantId passed in multi-tenant setups; definition not yet deployed when the message arrives.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Cannot find plan item
• Cannot find process definition for key
• Cannot find processInstance for id
• Cannot start process instance by message: message name is…
• Cannot start process instance by message: no subscription…

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

Appendix: source

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

        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();

        ProcessDefinitionEntity processDefinition = (ProcessDefinitionEntity) deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);
        if (processDefinition == null) {
            throw new ActivitiObjectNotFoundException("No process definition found for id '" + processDefinitionId + "'", ProcessDefinition.class);
        }

        // Do not start process a process instance if the process definition is suspended
        if (deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {

View on GitHub (pinned to d6d39ce1c6)