flowable/flowable-engine · error · ActivitiException

Cannot start process instance. Process definition

Error message

Cannot start process instance. Process definition <processDefinitionName> (id = <processDefinitionId>) is suspended

What it means

Thrown by StartProcessInstanceByMessageCmd.execute() when the process definition that a message event subscription points to is currently suspended. The engine refuses to start new process instances from a suspended definition, since suspended definitions may not spawn new executions. It is a plain ActivitiException carrying the definition name and id.

Solutions

  1. Resume the definition first: RepositoryService.activateProcessDefinitionById(processDefinitionId) (or byKey), then retry starting the instance.
  2. If suspension was intentional, stop sending/correlating messages to that definition and route to an active version or queue the messages until activation.
  3. Check suspension state before starting: processDefinition.isSuspended() via RepositoryService.getProcessDefinition(id), and guard the call.
  4. If a whole deployment is suspended, activate the deployment or the specific definition version your message start event belongs to.

Example fix

// before
runtimeService.startProcessInstanceByMessage("orderReceived", businessKey, vars); // throws when suspended
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("orderProcess").latestVersion().singleResult();
if (pd.isSuspended()) {
    repositoryService.activateProcessDefinitionById(pd.getId(), true, null);
}
runtimeService.startProcessInstanceByMessage("orderReceived", businessKey, vars);
Defensive patterns

Strategy: validation

Validate before calling

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionId(processDefinitionId).singleResult();
if (pd == null || pd.isSuspended()) {
    throw new IllegalStateException("Definition missing or suspended: " + processDefinitionId);
}

Try / catch

try {
    runtimeService.startProcessInstanceByMessage(messageName, businessKey, vars);
} catch (ActivitiException e) {
    if (e.getMessage() != null && e.getMessage().contains("is suspended")) {
        repositoryService.activateProcessDefinitionByKey(definitionKey, true, null);
        // retry once
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Calling RuntimeService.startProcessInstanceByMessage(...) (or message start event correlation) while the target process definition has been suspended via RepositoryService.suspendProcessDefinitionById/key (with or without includeProcessInstances).

Common situations: An admin suspended a definition version for a business freeze or a redeployment, and an application or message listener still correlates messages to that definition; batch jobs starting instances during a maintenance window; race between suspend operation and in-flight message delivery.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

        }

        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());
        ExecutionEntity processInstance = processDefinition.createProcessInstance(businessKey, startActivity);

        if (processVariables != null) {
            processInstance.setVariables(processVariables);
        }
        if (transientVariables != null) {
            processInstance.setTransientVariables(transientVariables);
        }

        processInstance.start();

        return processInstance;
    }

View on GitHub (pinned to d6d39ce1c6)