flowable/flowable-engine · error · ActivitiException

process instance is suspended, cannot set name

Error message

process instance <processInstanceId> is suspended, cannot set name

What it means

SetProcessInstanceNameCmd throws ActivitiException when the target process instance is suspended. The engine blocks name changes on suspended instances because a suspended instance must not receive mutations until resumed. The command aborts before setting the name or recording history.

Solutions

1. Resume the instance with runtimeService.activateProcessInstanceById(processInstanceId), set the name, then re-suspend if needed.
2. Check suspension state beforehand via ProcessInstanceQuery.suspended() and skip or queue the rename.
3. Avoid suspending instances that pending administration operations still need to modify.

Example fix

// before
runtimeService.setProcessInstanceName(processInstanceId, "monthly-run");
// after
runtimeService.activateProcessInstanceById(processInstanceId);
runtimeService.setProcessInstanceName(processInstanceId, "monthly-run");

boolean suspended = runtimeService.createProcessInstanceQuery().processInstanceId(processInstanceId).suspended().count() > 0;
if (suspended) runtimeService.activateProcessInstanceById(processInstanceId);

try {
    runtimeService.setProcessInstanceName(processInstanceId, name);
} catch (ActivitiException e) {
    logger.warn("Instance {} suspended; rename skipped", processInstanceId, e);
}

When it happens

Trigger: Calling RuntimeService.setProcessInstanceName(processInstanceId, name) on an instance paused via runtimeService.suspendProcessInstanceById(...) or suspended through its process definition.

Common situations: Admin renaming an instance on maintenance hold; bulk suspension by definition applied before the rename; race between a suspension sweep and a rename job.

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 find processInstance for id
• Cannot set suspension state for execution
• Cannot throw signal event
• Could not handle signal: no process instance started
• No process instance found for id

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

Appendix: source

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

        if (processInstanceId == null) {
            throw new ActivitiIllegalArgumentException("processInstanceId is null");
        }

        ExecutionEntity execution = commandContext
                .getExecutionEntityManager()
                .findExecutionById(processInstanceId);

        if (execution == null) {
            throw new ActivitiObjectNotFoundException("process instance " + processInstanceId + " doesn't exist", ProcessInstance.class);
        }

        if (!execution.isProcessInstanceType()) {
            throw new ActivitiObjectNotFoundException("process instance " + processInstanceId +
                    " doesn't exist, the given ID references an execution, though", ProcessInstance.class);
        }

        if (execution.isSuspended()) {
            throw new ActivitiException("process instance " + processInstanceId + " is suspended, cannot set name");
        }

        // Actually set the name
        execution.setName(name);

        // Record the change in history
        commandContext.getHistoryManager().recordProcessInstanceNameChange(processInstanceId, name);

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)