flowable/flowable-engine · error · FlowableException

process instance ${processInstanceId} is suspended, cannot s

Error message

process instance ${processInstanceId} is suspended, cannot set name

What it means

SetProcessInstanceNameCmd refuses to rename a suspended process instance. Flowable suspends instances to freeze them; mutating the name while suspended could conflict with suspension bookkeeping, so the command rejects it with a plain FlowableException.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessInstanceNameCmd.java:69

                Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
                if (compatibilityHandler != null) {
                    ProcessInstance processInstance = compatibilityHandler.getProcessInstance(processInstanceId);
                    if (processInstance != null) {
                        compatibilityHandler.setProcessInstanceName(processInstance.getId(), name);
                        return null;
                    }
                }
            }
            
            throw new FlowableObjectNotFoundException("process instance " + processInstanceId + " doesn't exist", ProcessInstance.class);
        }
        
        if (!execution.isProcessInstanceType()) {
            throw new FlowableObjectNotFoundException("process instance " + processInstanceId + " doesn't exist, the given ID references an execution, though", ProcessInstance.class);
        }

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

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

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

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Resume the instance first with runtimeService.activateProcessInstanceById(id), set the name, then suspend again if needed.
2. Skip suspended instances in batch logic, or check runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult().isSuspended() beforehand.
3. If suspension came from the process definition, evaluate whether the rename is really needed while suspended.

Example fix

// before
runtimeService.setProcessInstanceName(id, name);
// after
runtimeService.activateProcessInstanceById(id);
runtimeService.setProcessInstanceName(id, name);
runtimeService.suspendProcessInstanceById(id);

ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult();
if (pi != null && !pi.isSuspended()) {
    runtimeService.setProcessInstanceName(id, name);
}

try {
    runtimeService.setProcessInstanceName(id, name);
} catch (FlowableException e) {
    if (e.getMessage().contains("is suspended")) {
        runtimeService.activateProcessInstanceById(id);
        runtimeService.setProcessInstanceName(id, name);
    }
}

When it happens

Trigger: Calling runtimeService.setProcessInstanceName(id, name) while the instance is suspended via runtimeService.suspendProcessInstanceById(id) or by a suspended process definition.

Common situations: Batch renames applied to instances that an administrator suspended for maintenance; instances auto-suspended because their process definition was suspended.

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 add a comment to a suspended {execution}
• Process instance is still running, cannot delete
• Cannot throw signal event '${eventName}' because ${execution
• Could not start process instance with business key ${key}
• Task ${taskId} is already deleted

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