flowable/flowable-engine · error · FlowableException

Unhandled exception on camel route

Error message

Unhandled exception on camel route

What it means

After a Camel exchange completes with an exception, handleCamelException tries to map it to BPMN error handling via mapException (Flowable5 path first). If the exception matches no mapException entry and no error handling applies, FlowableException 'Unhandled exception on camel route' is thrown with the Camel exception as cause (V5 path).

Source

Thrown at modules/flowable-camel/src/main/java/org/flowable/camel/CamelBehavior.java:189

    protected boolean handleCamelException(Exchange exchange, DelegateExecution execution, boolean isV5Execution) {
        Exception camelException = exchange.getException();
        boolean notHandledByCamel = exchange.isFailed() && camelException != null;
        if (notHandledByCamel) {
            if (camelException instanceof BusinessError) {
                if (isV5Execution) {
                    Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
                    compatibilityHandler.propagateError((BpmnError) camelException, execution);
                    return true;
                }
                ErrorPropagation.propagateError((BusinessError) camelException, execution);
                return true;
            } else {
                if (isV5Execution) {
                    Flowable5CompatibilityHandler ompatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
                    if (ompatibilityHandler.mapException(camelException, execution, mapExceptions)) {
                        return true;
                    } else {
                        throw new FlowableException("Unhandled exception on camel route", camelException);
                    }
                }

                if (ErrorPropagation.mapException(camelException, (ExecutionEntity) execution, mapExceptions)) {
                    return true;
                } else {
                    throw new FlowableException("Unhandled exception on camel route", camelException);
                }
            }
        }
        return false;
    }

    protected void copyVariablesToProperties(Map<String, Object> variables, Exchange exchange) {
        for (Map.Entry<String, Object> var : variables.entrySet()) {
            exchange.setProperty(var.getKey(), var.getValue());
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add a mapException entry on the activity matching the exception class
2. Attach a boundary error event to the service task to catch the error
3. Fix the Camel route so it doesn't throw (or handle the exception inside the route with onException/doTry)
4. Inspect getCause() to identify the original Camel exception

Example fix

<!-- after: map the camel exception -->
<serviceTask id="camelTask" flowable:type="camel">
  <flowable:mapException errorCode="CAMEL_ERR" exceptionClass="com.acme.MyBusinessException" andChildren="true"/>
</serviceTask>

catch (FlowableException e) { if (e.getMessage().contains("Unhandled exception on camel route")) { /* fallback handling using e.getCause() */ } }

When it happens

Trigger: Camel route throws an exception during execution of a V5-compatible activity; no mapException entries match the exception class; no errorBoundaryEvent/handler exists on the activity.

Common situations: Business exceptions thrown in Camel beans without error handling in the BPMN model; upgrading/maintaining Flowable5 compatibility routes.

Related errors

• Exception while processing exchange
• Endpoint not defined for ${key}
• Initiator header '${processInitiatorHeaderName}': Value must
• Initiator header '${processInitiatorHeaderName}': Value must
• Consumer not defined for ${endpointUri}

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