flowable/flowable-engine · error · FlowableException

process instance is suspended, cannot set name

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.

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
• Cannot throw signal event
• Process instance is still running, cannot delete
• A process instance id is required, but the provided id '" +…
• A process instance id is required, but the provided id

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

Appendix: 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)