What causes "Cannot start process instance by message: subscription to message with name ' ' is not a message start event." in flowable/flowable-engine?

Redeploy the process definition containing the message start event so the subscription is recreated with a valid configuration.

flowable/flowable-engine · error · ActivitiException

Cannot start process instance by message: subscription to…

Error message

Cannot start process instance by message: subscription to message with name '<messageName>' is not a message start event.

What it means

StartProcessInstanceByMessageCmd throws ActivitiException when the message start-event subscription found for the message name has a null configuration, meaning its processDefinitionId could not be resolved. A valid message start subscription must point at a deployed process definition; a dangling subscription indicates corrupted or incompletely deployed state, so the command aborts.

Solutions

Redeploy the process definition containing the message start event so the subscription is recreated with a valid configuration.
Clean orphaned subscriptions in ACT_RU_EVENT_SUBSCRIPTION (message-type rows with CONFIGURATION_ IS NULL) after backing up the DB.
Check deployment integrity with repositoryService.createDeploymentQuery() and verify the definition exists before correlating.

Example fix

// before
runtimeService.startProcessInstanceByMessage("OrderReceived");
// after
List<EventSubscription> subs = repositoryService.createEventSubscriptionQuery().eventName("OrderReceived").list();
if (subs.isEmpty()) {
    throw new IllegalStateException("No message start subscription deployed for OrderReceived");
}
runtimeService.startProcessInstanceByMessage("OrderReceived");

Defensive patterns

Strategy: validation

Validate before calling

List<EventSubscription> subs = repositoryService.createEventSubscriptionQuery().eventName(messageName).list();
boolean healthy = !subs.isEmpty() && subs.get(0).getConfiguration() != null;

Try / catch

try {
    runtimeService.startProcessInstanceByMessage(messageName);
} catch (ActivitiException e) {
    logger.error("Corrupt message subscription for '{}' — redeploy required", messageName, e);
}

Prevention

Never manipulate ACT_RU_EVENT_SUBSCRIPTION or definition tables with manual SQL.
Verify deployment integrity after DB restores or engine-version migrations.
Keep deletes of definitions and subscriptions atomic (cascade).

When it happens

Trigger: Correlating a message whose start-event subscription row in ACT_RU_EVENT_SUBSCRIPTION has CONFIGURATION_ null — typically after a partial/broken deployment or manual data manipulation.

Common situations: Deployment deleted while subscriptions leaked; database migration between engine versions leaving stale rows; manual SQL cleanup removing process definition rows but not event subscriptions.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

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

    }

    @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())) {
            throw new ActivitiException("Cannot start process instance. Process definition "
                    + processDefinition.getName() + " (id = " + processDefinition.getId() + ") is suspended");
        }

        ActivityImpl startActivity = processDefinition.findActivity(messageEventSubscription.getActivityId());

View on GitHub (pinned to d6d39ce1c6)