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

CallActivityBehavior.execute() resolves the called process definition and checks whether it is suspended before instantiating the subprocess. If the definition is suspended, it throws ActivitiException and refuses to start a new process instance of it.

Solutions

Resume the definition with runtimeService.activateProcessDefinitionByKey(key) (or byId) including the right tenant handling
Delay or reroute execution of the parent process until the subprocess definition is active
Suspend only process instances, not the definition, if new subprocess starts should remain possible
Coordinate suspension windows with process migration/completion of parent instances

Example fix

// before
runtimeService.suspendProcessDefinitionByKey("subProcess");
// after (resume when needed)
runtimeService.activateProcessDefinitionByKey("subProcess", true, null);

Defensive patterns

Strategy: try-catch

Validate before calling

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(key).latestVersion().singleResult();
if (pd != null && pd.isSuspended()) { /* delay or resume before parent reaches call activity */ }

Try / catch

try { runtimeService.signal(executionId); }
catch (ActivitiException e) { if (e.getMessage().contains("is suspended")) { runtimeService.activateProcessDefinitionByKey(key); retry(); } }

Prevention

Coordinate definition suspension with in-flight instances
Prefer suspending instances instead of definitions when parents still run
Check isSuspended in monitoring jobs

When it happens

Trigger: A call activity executes while its referenced process definition (by key, or key+version, or key+tenant) has been suspended via RuntimeService.suspendProcessDefinitionByKey/ById.

Common situations: Administrators suspend a definition for maintenance or a release freeze but a running parent process still reaches the call activity; suspension applied to 'latest' while in-flight instances continue.

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/2c998571bc6aaee7. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/bpmn/behavior/CallActivityBehavior.java:106

        ProcessDefinition processDefinition = null;

        if (sameDeployment) {
            String deploymentId = deploymentManager.findDeployedProcessDefinitionById(execution.getProcessDefinitionId()).getDeploymentId();
            processDefinition = Context.getCommandContext().getProcessDefinitionEntityManager().findProcessDefinitionByDeploymentAndKey(deploymentId, processDefinitonKey);
            processDefinition = deploymentManager.findDeployedProcessDefinitionById(processDefinition.getId());
        }

        if (processDefinition == null) {
            if (execution.getTenantId() == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(execution.getTenantId())) {
                processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKey(processDefinitonKey);
            } else {
                processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKeyAndTenantId(processDefinitonKey, execution.getTenantId());
            }
        }

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

        ActivityExecution activityExecution = (ActivityExecution) execution;
        PvmProcessInstance subProcessInstance = activityExecution.createSubProcessInstance((ProcessDefinitionEntity) processDefinition);

        if (inheritVariables) {
            Map<String, Object> variables = execution.getVariables();
            for (Map.Entry<String, Object> entry : variables.entrySet()) {
                subProcessInstance.setVariable(entry.getKey(), entry.getValue());
            }
        }

        String subProcessInstanceBusinessKey = null;
        if (StringUtils.isNotEmpty(businessKey)) {
            ExpressionManager expressionManager = processEngineConfiguration.getExpressionManager();
            Expression expression = expressionManager.createExpression(businessKey);
            subProcessInstanceBusinessKey = expression.getValue(execution).toString();

View on GitHub (pinned to d6d39ce1c6)