flowable/flowable-engine · error · ActivitiException

Cannot execute operation because process definition '" +…

Error message

Cannot execute operation because process definition '" + processDefinition.getName() + "' (id=" + processDefinition.getId() + ") is suspended

What it means

Thrown by NeedsActiveProcessDefinitionCmd.execute() when the target process definition is suspended. The command resolves the deployed definition via the DeploymentManager and refuses to proceed while isProcessDefinitionSuspended returns true, raising an ActivitiException naming the definition and its id. New operations against that definition version are blocked until it is activated.

Solutions

1. Re-activate the definition: repositoryService.activateProcessDefinitionById(id) or activateProcessDefinitionByKey(key).
2. Check suspension first: repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult().isSuspended().
3. Deploy or point to a newer active version instead of operating on the suspended one.
4. If suspension is intentional, block the user action at the application layer before invoking the engine.

Example fix

// before
runtimeService.startProcessInstanceById(processDefinitionId);

// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionId(processDefinitionId).singleResult();
if (pd.isSuspended()) {
    repositoryService.activateProcessDefinitionById(pd.getId());
}
runtimeService.startProcessInstanceById(processDefinitionId);

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult();
if (pd != null && pd.isSuspended()) throw new IllegalStateException("definition suspended: " + id);

try {
    runtimeService.startProcessInstanceById(id);
} catch (ActivitiException e) {
    if (e.getMessage() != null && e.getMessage().contains("is suspended")) {
        repositoryService.activateProcessDefinitionById(id);
    }
}

When it happens

Trigger: Starting a process instance (e.g. runtimeService.startProcessInstanceById/ByKey pinned to a version) or any command extending NeedsActiveProcessDefinitionCmd while the definition was suspended through repositoryService.suspendProcessDefinitionById/ByKey (including suspendProcessInstances flag).

Common situations: Ops teams suspend a definition during a migration or bugfix freeze; a form or API still points at an old suspended version; default (latest) version resolution lands on a suspended deployment.

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 execute operation: task is suspended
• Cannot execution operation because execution '" +…
• Ad-hoc sub process has running child executions that need…
• Candidate group is null
• Candidate group list is empty

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

Appendix: source

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

 * @author Joram Barrez
 */
public abstract class NeedsActiveProcessDefinitionCmd<T> implements Command<T>, Serializable {

    private static final long serialVersionUID = 1L;

    protected String processDefinitionId;

    public NeedsActiveProcessDefinitionCmd(String processDefinitionId) {
        this.processDefinitionId = processDefinitionId;
    }

    @Override
    public T execute(CommandContext commandContext) {
        DeploymentManager deploymentManager = commandContext.getProcessEngineConfiguration().getDeploymentManager();
        ProcessDefinition processDefinition = deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);

        if (deploymentManager.isProcessDefinitionSuspended(processDefinitionId)) {
            throw new ActivitiException("Cannot execute operation because process definition '"
                    + processDefinition.getName() + "' (id=" + processDefinition.getId() + ") is suspended");
        }

        return execute(commandContext, processDefinition);
    }

    /**
     * Subclasses should implement this. The provided {@link ProcessDefinition} is guaranteed to be an active process definition (ie. not suspended).
     */
    protected abstract T execute(CommandContext commandContext, ProcessDefinition processDefinition);

}

View on GitHub (pinned to d6d39ce1c6)