flowable/flowable-engine · error · FlowableObjectNotFoundException

Cannot start process instance by message: no subscription to

Error message

Cannot start process instance by message: no subscription to message with name '${messageName}' found.

What it means

No message start event subscription with the given message name (and tenant) exists, so the command cannot correlate the message to any deployable process start. Flowable only registers start subscriptions when a deployed process definition contains a message start event with that name.

Source

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

        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);
        if (processDefinition == null) {
            throw new FlowableObjectNotFoundException("No process definition found for id '" + processDefinitionId + "'", ProcessDefinition.class);
        }

        ProcessInstanceHelper processInstanceHelper = processEngineConfiguration.getProcessInstanceHelper();
        ProcessInstance processInstance = processInstanceHelper.createAndStartProcessInstanceByMessage(processDefinition,
                messageName, businessKey, businessStatus, processVariables, transientVariables, callbackId, callbackType, referenceId, referenceType,
                ownerId, assigneeId);

View on GitHub (pinned to d6d39ce1c6)

Solutions

Verify the BPMN start event is a messageStartEvent and its message name exactly matches (case-sensitive) the name passed to the API.
Confirm the process definition containing the message start event is deployed to the same engine (check via repositoryService).
In multi-tenant setups, pass the correct tenantId used at deployment time.
List candidate subscriptions in the ACT_RU_EVENT_SUBSCR table (or via queries) to see which message names are actually registered.

Example fix

// before
runtimeService.startProcessInstanceByMessageAndTenantId("RecieveOrder", tenantId);
// after
// BPMN: <message id="orderMsg" name="ReceiveOrder"/> on a messageStartEvent
runtimeService.startProcessInstanceByMessageAndTenantId("ReceiveOrder", tenantId);

Defensive patterns

Strategy: validation

Validate before calling

ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .messageEventSubscriptionName(messageName)
    .processDefinitionTenantId(tenantId)
    .latestVersion().singleResult();
if (def != null) {
    runtimeService.startProcessInstanceByMessageAndTenantId(messageName, tenantId);
}

Try / catch

try {
    runtimeService.startProcessInstanceByMessageAndTenantId(messageName, tenantId);
} catch (FlowableObjectNotFoundException e) {
    log.error("No message start event subscribed for '{}' (tenant {})", messageName, tenantId, e);
}

Prevention

Keep BPMN message names in constants shared between process models and calling code
Deploy the process containing the message start event before external messages arrive
In multi-tenant setups always pass the tenantId used at deployment time
Inspect ACT_RU_EVENT_SUBSCR to confirm which message names are registered

When it happens

Trigger: Calling runtimeService.startProcessInstanceByMessage(messageName[, tenantId]) when no deployed process has a message start event with that exact name, the process was undeployed, or the tenantId doesn't match the deployment tenant.

Common situations: Name mismatch or case difference between BPMN message name and caller; process not (re)deployed before the message arrives; multi-tenant deployments where the message is sent with the wrong tenantId; new-definition deployment removed the old message start event.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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