flowable/flowable-engine · error · FlowableException

Ad-hoc sub process has running child executions that need…

Error message

Ad-hoc sub process has running child executions that need to be completed first.

What it means

Before completing an ad-hoc sub-process, all its child executions must be finished. Flowable throws FlowableException when the ad-hoc sub-process still has running child executions (e.g. active ad-hoc tasks).

Solutions

Complete or delete the running child executions/tasks inside the ad-hoc sub-process first.
Use runtimeService.deleteProcessInstance or cancel the child executions if the remaining work should be discarded.
Query child executions (runtimeService.createExecutionQuery().parentId(executionId)) and handle each before completing.

Example fix

// before
runtimeService.completeAdhocSubProcess(executionId, outcome); // children still running
// after
List<Execution> children = runtimeService.createExecutionQuery().parentId(executionId).list();
if (children.isEmpty()) {
    runtimeService.completeAdhocSubProcess(executionId, outcome);
}

Defensive patterns

Strategy: validation

Validate before calling

List<Execution> children = runtimeService.createExecutionQuery().parentId(executionId).list();
if (!children.isEmpty()) {
    throw new IllegalStateException("Complete or cancel child executions first");
}

Try / catch

try {
    runtimeService.completeAdhocSubProcess(executionId, outcome);
} catch (FlowableException e) {
    if (e.getMessage().contains("running child executions")) {
        // cancel or complete children, then retry
    }
}

Prevention

Before completing, enumerate and resolve all child executions/ad-hoc tasks.
Decide upfront whether remaining ad-hoc tasks should be completed or cancelled.

When it happens

Trigger: runtimeService.completeAdhocSubProcess(executionId, ...) while ad-hoc sub-process children (active tasks) are still running.

Common situations: Trying to complete the ad-hoc sub-process without terminating/cancelling remaining ad-hoc tasks; concurrent user tasks still open inside the sub-process.

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

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/CompleteAdhocSubProcessCmd.java:55

    public CompleteAdhocSubProcessCmd(String executionId) {
        this.executionId = executionId;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        ExecutionEntityManager executionEntityManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExecutionEntity execution = executionEntityManager.findById(executionId);
        if (execution == null) {
            throw new FlowableObjectNotFoundException("No execution found for id '" + executionId + "'", ExecutionEntity.class);
        }

        if (!(execution.getCurrentFlowElement() instanceof AdhocSubProcess)) {
            throw new FlowableException("The current flow element of the requested " + execution + " is not an ad-hoc sub process");
        }

        List<? extends ExecutionEntity> childExecutions = execution.getExecutions();
        if (childExecutions.size() > 0) {
            throw new FlowableException("Ad-hoc sub process has running child executions that need to be completed first. " + execution);
        }

        ExecutionEntity outgoingFlowExecution = executionEntityManager.createChildExecution(execution.getParent());
        outgoingFlowExecution.setCurrentFlowElement(execution.getCurrentFlowElement());

        executionEntityManager.deleteExecutionAndRelatedData(execution, null, false);

        CommandContextUtil.getAgenda().planTakeOutgoingSequenceFlowsOperation(outgoingFlowExecution, true);

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)