What causes "Error while propagating error-event" in flowable/flowable-engine?

Inspect the wrapped cause (getCause()) to see the underlying propagation failure and fix that first.

flowable/flowable-engine · error · ActivitiException

Error while propagating error-event

Error message

Error while propagating error-event

What it means

This ActivitiException wraps any failure that occurs while the event listener propagates a BPMN error event to an execution via ErrorPropagation.propagateError(errorCode, execution). It is thrown from ErrorThrowingEventListener.onEvent when an error-start/boundary-event style listener fires but the propagation itself fails (no matching boundary/error handler, or an internal exception during propagation). The original cause is attached as the wrapped exception.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/bpmn/helper/ErrorThrowingEventListener.java:52

        if (isValidEvent(event) && event instanceof FlowableEngineEvent) {
            FlowableEngineEvent engineEvent = (FlowableEngineEvent) event;
            ExecutionEntity execution = null;

            if (Context.isExecutionContextActive()) {
                execution = Context.getExecutionContext().getExecution();
            } else if (engineEvent.getExecutionId() != null) {
                // Get the execution based on the event's execution ID instead
                execution = Context.getCommandContext().getExecutionEntityManager().findExecutionById(engineEvent.getExecutionId());
            }

            if (execution == null) {
                throw new ActivitiException("No execution context active and event is not related to an execution. No compensation event can be thrown.");
            }

            try {
                ErrorPropagation.propagateError(errorCode, execution);
            } catch (Exception e) {
                throw new ActivitiException("Error while propagating error-event", e);
            }
        }
    }

    public void setErrorCode(String errorCode) {
        this.errorCode = errorCode;
    }

    @Override
    public boolean isFailOnException() {
        return true;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the wrapped cause (getCause()) to see the underlying propagation failure and fix that first.
Verify the listener's errorCode exactly matches the errorRef of a boundary error event or error start event in the process definition.
Ensure the event the listener is bound to is execution-related; do not register the error-throwing listener for events without an execution context.
Check the process definition has an error handler (boundaryEvent with errorEventDefinition) in an enclosing scope for the activity where the event fires.
Log/step through ErrorPropagation.propagateError to see whether any scope matched the error code.

Example fix

// before: listener fires, but no matching error handler
<extensionElements>
  <activiti:eventListener events="TASK_COMPLETED" errorCode="MY_ERROR"/>
</extensionElements>

// after: add a matching boundary error handler with errorRef="MY_ERROR"
<boundaryEvent id="errBoundary" attachedToRef="theTask">
  <errorEventDefinition errorRef="MY_ERROR"/>
</boundaryEvent>

Defensive patterns

Strategy: try-catch

Validate before calling

// before relying on the listener, confirm a matching error handler exists
boolean hasHandler = process.getFlowElements().stream()
    .filter(BoundaryEvent.class::isInstance)
    .map(BoundaryEvent.class::cast)
    .flatMap(be -> be.getEventDefinitions().stream())
    .filter(ErrorEventDefinition.class::isInstance)
    .map(ed -> ((ErrorEventDefinition) ed).getErrorCode())
    .anyMatch(code -> code == null || code.equals("MY_ERROR"));
if (!hasHandler) throw new IllegalStateException("No error handler for errorCode MY_ERROR");

Try / catch

try {
    eventDispatcher.dispatchEvent(myEvent);
} catch (ActivitiException e) {
    logger.error("error-event propagation failed, cause={} ", e.getCause(), e);
    throw e;
}

Prevention

Always pair an error-throwing event listener errorCode with a boundary/error-start event errorRef.
Register error-throwing listeners only on execution-related events.
Keep errorCode strings as constants shared between listener config and error definitions.
Log the wrapped cause, not just the outer message, when debugging propagation failures.

When it happens

Trigger: A Flowable event (e.g. TASK_COMPLETED, ACTIVITY_SIGNALLED, etc.) is dispatched to a registered ErrorThrowingEventListener with an errorCode; ErrorPropagation.propagateError is invoked but throws — e.g. no scope/execution context available, no matching error boundary event or error start event exists for the errorCode, or an exception occurs while searching the execution hierarchy.

Common situations: Configuring an error-throwing event listener in the process definition whose errorCode does not match any boundary error event or error start event in the process; firing the listener from a global event (no execution context) so the error cannot be attached to an execution; typos in errorCode values; cascading failures inside an error handler triggered during rollback.

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/bdcf73b501cfd57c. Report an issue: GitHub.