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 StartProcessInstanceCmd.execute() as ActivitiException when the resolved process definition is suspended; the engine refuses to create a new process instance. The message names the definition's name and id so the offending definition is easy to identify.

Solutions

1. Activate it: RepositoryService.activateProcessDefinitionById(id, includeProcessInstances, activationDate) or activateProcessDefinitionByKey, then retry.
2. If the suspension is intentional, block new starts in the application and reject/queue requests gracefully.
3. Start from a non-suspended version: choose an active latest version via ProcessDefinitionQuery().active().latestVersion().
4. Check isSuspended() on the definition before starting and surface a friendly error to users.

Example fix

// before
runtimeService.startProcessInstanceByKey("orderProcess"); // throws: definition suspended
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("orderProcess").latestVersion().singleResult();
if (pd.isSuspended()) {
    repositoryService.activateProcessDefinitionById(pd.getId(), true, null);
}
runtimeService.startProcessInstanceByKey("orderProcess");

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(definitionKey).latestVersion().singleResult();
if (pd != null && pd.isSuspended()) {
    throw new IllegalStateException("Definition suspended: " + pd.getName());
}

try {
    return runtimeService.startProcessInstanceByKey(definitionKey, vars);
} catch (ActivitiException e) {
    if (e.getMessage() != null && e.getMessage().contains("is suspended")) {
        throw new ProcessSuspendedException(definitionKey, e);
    }
    throw e;
}

When it happens

Trigger: RuntimeService.startProcessInstanceById/ByKey after the target definition was suspended via RepositoryService.suspendProcessDefinitionById/Key(...); scheduled starters or API endpoints invoked during a business suspension window.

Common situations: Maintenance/business freezes where definitions are suspended intentionally; redeployments that suspend old versions while clients still call the old key/version; default behavior of suspending a definition without realizing it blocks new instances.

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

• Cannot start process instance. Process definition
• Cannot find process definition for key
• Cannot start process instance. Process definition
• No process definition found for id ''
• No process definition found for id =

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

Appendix: source

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

                throw new ActivitiObjectNotFoundException("No process definition found for id = '" + processDefinitionId + "'", ProcessDefinition.class);
            }
        } else if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {
            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKey(processDefinitionKey);
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException("No process definition found for key '" + processDefinitionKey + "'", ProcessDefinition.class);
            }
        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {
            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);
            if (processDefinition == null) {
                throw new ActivitiObjectNotFoundException("No process definition found for key '" + processDefinitionKey + "' for tenant identifier " + tenantId, ProcessDefinition.class);
            }
        } else {
            throw new ActivitiIllegalArgumentException("processDefinitionKey and processDefinitionId are null");
        }

        // 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");
        }

        // Start the process instance
        ExecutionEntity processInstance = ((ProcessDefinitionEntity) processDefinition).createProcessInstance(businessKey);

        // now set the variables passed into the start command
        initializeVariables(processInstance);

        // now set processInstance name
        if (processInstanceName != null) {
            processInstance.setName(processInstanceName);
            commandContext.getHistoryManager().recordProcessInstanceNameChange(processInstance.getId(), processInstanceName);
        }

        processInstance.start();

        return processInstance;

View on GitHub (pinned to d6d39ce1c6)