flowable/flowable-engine · error · FlowableException

Programmatic error: sub process behaviour can only be applie

Error message

Programmatic error: sub process behaviour can only be applied to a SubProcess instance, but got an instance of + flowElement + for + execution

What it means

This is a programmatic/invariant check: the behavior bound to the current flow element must be a SubProcess, but the element resolved from execution.getCurrentFlowElement() is some other FlowElement type. It indicates the execution state and the activity behavior are out of sync, i.e. an internal engine misuse rather than user input.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/SubProcessActivityBehavior.java:103

                            return startEvent;
                        }
                        
                    } else {
                        return startEvent;
                    }
                }
            }
        }
        return null;
    }

    protected SubProcess getSubProcessFromExecution(DelegateExecution execution) {
        FlowElement flowElement = execution.getCurrentFlowElement();
        SubProcess subProcess = null;
        if (flowElement instanceof SubProcess) {
            subProcess = (SubProcess) flowElement;
        } else {
            throw new FlowableException(
                    "Programmatic error: sub process behaviour can only be applied to a SubProcess instance, but got an instance of " + flowElement + " for "
                            + execution);
        }
        return subProcess;
    }

    protected Map<String, Object> processDataObjects(Collection<ValuedDataObject> dataObjects) {
        Map<String, Object> variablesMap = new HashMap<>();
        // convert data objects to process variables
        if (dataObjects != null) {
            for (ValuedDataObject dataObject : dataObjects) {
                variablesMap.put(dataObject.getName(), dataObject.getValue());
            }
        }
        return variablesMap;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Ensure the activity behavior for the element is created by the default BehaviorFactory for SubProcess elements, not assigned manually
Verify custom BpmnParseHandler / ActivityBehaviorFactory overrides only apply this behavior to SubProcess instances
Check execution.getCurrentFlowElement() type before invoking the behavior in custom code
If seen during an upgrade, clear the act_ge_bytearray/act_re_procdef of stale deployments and redeploy

Example fix

// before
someOtherElement.setBehavior(new SubProcessActivityBehavior());
// after
if (flowElement instanceof SubProcess) {
    ((SubProcess) flowElement).setBehavior(new SubProcessActivityBehavior());
}

Defensive patterns

Strategy: type-guard

Validate before calling

FlowElement fe = execution.getCurrentFlowElement();
if (!(fe instanceof SubProcess)) {
    throw new IllegalStateException("Expected SubProcess, got " + fe.getClass());
}

Type guard

if (execution.getCurrentFlowElement() instanceof SubProcess) { /* safe */ }

Try / catch

try {
    subProcessBehavior.execute(execution);
} catch (FlowableException e) {
    logger.error("Behavior/element mismatch", e);
}

Prevention

Do not manually assign SubProcessActivityBehavior to non-SubProcess elements
Let the default BehaviorFactory create behaviors
Audit custom BpmnParseHandlers after engine upgrades

When it happens

Trigger: A DelegateExecution whose currentFlowElement is not an org.flowable.bpmn.model.SubProcess is passed into SubProcessActivityBehavior (e.g. custom code attaching the wrong behavior class to an element, or reusing the behavior outside its intended element type).

Common situations: Custom behavior/parse-handler code assigning SubProcessActivityBehavior to a different node type; engine upgrades where execution state changed; reflection-driven testing that feeds the wrong flow element.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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