flowable/flowable-engine · error · FlowableException

getSuspendedTaskExceptionPrefix() + " a suspended " + task

Error message

getSuspendedTaskExceptionPrefix() + " a suspended " + task

What it means

NeedsActiveTaskCmd blocks all operations on suspended tasks: after the null/deleted checks, isSuspended() triggers a FlowableException built from getSuspendedTaskExceptionPrefix(). Tasks become suspended when their process instance or process definition is suspended via RuntimeService/RepositoryService.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/NeedsActiveTaskCmd.java:61

    public T execute(CommandContext commandContext) {

        if (taskId == null) {
            throw new FlowableIllegalArgumentException("taskId is null");
        }

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        TaskEntity task = processEngineConfiguration.getTaskServiceConfiguration().getTaskService().getTask(taskId);

        if (task == null) {
            throw new FlowableObjectNotFoundException("Cannot find task with id " + taskId, Task.class);
        }

        if (task.isDeleted()) {
            throw new FlowableException(task + " is already deleted");
        }

        if (task.isSuspended()) {
            throw new FlowableException(getSuspendedTaskExceptionPrefix() + " a suspended " + task);
        }

        return execute(commandContext, task);
    }

    /**
     * Subclasses must implement in this method their normal command logic. The provided task is ensured to be active.
     */
    protected abstract T execute(CommandContext commandContext, TaskEntity task);

    /**
     * Subclasses can override this method to provide a customized exception message that will be thrown when the task is suspended.
     */
    protected String getSuspendedTaskExceptionPrefix() {
        return "Cannot execute operation for";
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Reactivate the owning process instance/definition (activateProcessInstanceById / activateProcessDefinitionById) and retry the task operation.
2. Filter the task inbox to exclude suspended tasks: taskService.createTaskQuery().taskId(id).active() or .suspended() checks.
3. Catch FlowableException and inform the user the task is temporarily frozen pending reactivation.
4. Schedule user-task maintenance only after draining or freezing the inbox accordingly.

Example fix

// before
taskService.claim(taskId, userId);
// after
Task task = taskService.createTaskQuery().taskId(taskId).singleResult();
if (task != null && task.isSuspended()) {
    throw new IllegalStateException("Task is suspended; reactivate the process instance first");
}
taskService.claim(taskId, userId);

Task task = taskService.createTaskQuery().taskId(taskId).singleResult();
if (task != null && task.isSuspended()) { throw new IllegalStateException("Task is suspended"); }

try {
    taskService.claim(taskId, userId);
} catch (FlowableException e) {
    if (e.getMessage().contains("suspended")) {
        throw new ServiceUnavailableException("Task temporarily suspended");
    }
    throw e;
}

When it happens

Trigger: Claiming, completing, delegating or otherwise modifying a task belonging to a suspended process instance (RuntimeService.suspendProcessInstanceById) or suspended process definition.

Common situations: Admin froze a definition/instance during a migration window while users still work their inboxes; batch jobs claim tasks from suspended instances; test environments where fixtures were left 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

• a suspended
• Task ${taskId} is already deleted
• Child task variables can only be set when starting a plan it
• Child form variables can only be set when starting a plan it
• The source and the target tenant ids must be different.

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