flowable/flowable-engine · error · FlowableException

Cannot start process instance. Process definition ${processD

Error message

Cannot start process instance. Process definition ${processDefinition.getName()} (id = ${processDefinition.getId()}) is suspended

What it means

Before starting the sub process instance from a call activity, Flowable checks whether the resolved target process definition is suspended. If it is (suspension state set via the management API), starting is refused and this FlowableException is thrown. Suspension is an intentional administrative state, so the engine refuses to create new instances of it.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/CallActivityBehavior.java:116

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);

        ProcessDefinition processDefinition = getProcessDefinition(execution, callActivity, processEngineConfiguration);

        // Get model from cache
        Process subProcess = ProcessDefinitionUtil.getProcess(processDefinition.getId());
        if (subProcess == null) {
            throw new FlowableException("Cannot start a sub process instance. Process model " + processDefinition.getName() + " (id = " + processDefinition.getId() + ") could not be found");
        }

        FlowElement initialFlowElement = subProcess.getInitialFlowElement();
        if (initialFlowElement == null) {
            throw new FlowableException("No start element found for process definition " + processDefinition.getId());
        }

        // Do not start a process instance if the process definition is suspended
        if (ProcessDefinitionUtil.isProcessDefinitionSuspended(processDefinition.getId())) {
            throw new FlowableException("Cannot start process instance. Process definition " + processDefinition.getName() + " (id = " + processDefinition.getId() + ") is suspended");
        }

        ExecutionEntityManager executionEntityManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExpressionManager expressionManager = processEngineConfiguration.getExpressionManager();

        String businessKey = null;
        if (!StringUtils.isEmpty(callActivity.getBusinessKey())) {
            Expression expression = expressionManager.createExpression(callActivity.getBusinessKey());
            businessKey = expression.getValue(execution).toString();

        } else if (callActivity.isInheritBusinessKey()) {
            ExecutionEntity processInstance = executionEntityManager.findById(execution.getProcessInstanceId());
            businessKey = processInstance.getBusinessKey();
        }

        StartSubProcessInstanceBeforeContext instanceBeforeContext = new StartSubProcessInstanceBeforeContext(businessKey, null,
                callActivity.getProcessInstanceName(), new HashMap<>(), new HashMap<>(), executionEntity, callActivity.getInParameters(),
                callActivity.isInheritVariables(), initialFlowElement.getId(), initialFlowElement, subProcess, processDefinition);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Reactivate the definition: managementService.activateProcessDefinitionById(processDefinitionId) (optionally with activateProcessInstances).
2. If a different version should be used, suspend only the old version and point the call activity (calledElement) at the active version key.
3. Schedule the suspension window so the parent process does not reach the call activity, or migrate in-flight instances away from it.
4. Check suspension state first: repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult().isSuspended().

Example fix

// before: call activity fails because target definition is suspended
// after: reactivate before resuming the parent process
managementService.activateProcessDefinitionById("subProcess:2:456", true, null);

ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey("subProcess").latestVersion().singleResult();
if (def != null && def.isSuspended()) managementService.activateProcessDefinitionById(def.getId());

try { parent.resume(); }
catch (FlowableException e) { if (e.getMessage().contains("is suspended")) { managementService.activateProcessDefinitionById(defId); retryLater(); } else { throw e; } }

When it happens

Trigger: A call activity executes while the called sub-process definition (or one of its instances) was suspended via managementService.activateProcessDefinitionById/...ByIds being absent — i.e. the definition is in suspended state and a new sub instance start is attempted.

Common situations: Administrator suspended the sub process for maintenance or a version freeze and forgot to reactivate; long-running parent process hits the call activity during the suspension window; migration scripts suspend old definitions still referenced by call activities.

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 a sub process instance. Process model ${process
• Cannot complete process instance. Parent process instance ${
• Process definition ${processDefinitionKey} was not found in
• No process definition found for name:
• Process definition category is null

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