flowable/flowable-engine · error · FlowableException

Could not find eventhandler for event of type '${eventType}'

Error message

Could not find eventhandler for event of type '${eventType}' for ${eventSubscriptionEntity}

What it means

Flowable's event subscription processing looks up an EventHandler implementation registered on the ProcessEngineConfiguration for the event subscription's event type (e.g. message, signal, compensation). If no handler is registered for that event type, processEventSync throws this FlowableException rather than silently dropping the event. This indicates either a corrupted/unknown event subscription entity or a missing event-handler registration.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/EventSubscriptionUtil.java:79

                }
                
            } else {
                execution.setVariables(payloadMap);
            }
        }
    }

    protected static void processEventSync(EventSubscriptionEntity eventSubscriptionEntity, Object payload) {
        // A compensate event needs to be deleted before the handlers are called
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration();
        if (eventSubscriptionEntity instanceof CompensateEventSubscriptionEntity) {
            processEngineConfiguration.getEventSubscriptionServiceConfiguration().getEventSubscriptionService().deleteEventSubscription(eventSubscriptionEntity);
            CountingEntityUtil.handleDeleteEventSubscriptionEntityCount(eventSubscriptionEntity);
        }

        EventHandler eventHandler = processEngineConfiguration.getEventHandler(eventSubscriptionEntity.getEventType());
        if (eventHandler == null) {
            throw new FlowableException("Could not find eventhandler for event of type '" + eventSubscriptionEntity.getEventType() + "' for " + eventSubscriptionEntity);
        }
        eventHandler.handleEvent(eventSubscriptionEntity, payload, CommandContextUtil.getCommandContext());
    }

    protected static void scheduleEventAsync(EventSubscriptionEntity eventSubscriptionEntity, Object payload) {
        CommandContext commandContext = CommandContextUtil.getCommandContext();
        JobService jobService = CommandContextUtil.getJobService(commandContext);
        JobEntity message = jobService.createJob();
        message.setJobType(JobEntity.JOB_TYPE_MESSAGE);
        message.setJobHandlerType(ProcessEventJobHandler.TYPE);
        message.setElementId(eventSubscriptionEntity.getActivityId());
        message.setJobHandlerConfiguration(eventSubscriptionEntity.getId());
        message.setTenantId(eventSubscriptionEntity.getTenantId());
        
        String executionId = eventSubscriptionEntity.getExecutionId();
        
        if (StringUtils.isNotEmpty(executionId)) {
            ExecutionEntity execution = CommandContextUtil.getExecutionEntityManager(commandContext).findById(executionId);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Register an EventHandler for the event type via ProcessEngineConfiguration's event handler registry (custom event handlers must be registered on every engine instance).
2. Check for stale/orphaned rows in the event subscription tables (ACT_RU_EVENT_SUBSCR) with unknown event types and delete or correct them.
3. Verify all cluster nodes run identical engine versions and configuration so handler registrations match.
4. Confirm the event type string on the subscription matches the type a handler was registered under (case/typo check).

Example fix

// before: custom event thrown without handler
runtimeService.dispatchEvent(myCustomEvent);

// after: register handler first
processEngineConfiguration.setPostBpmnParseHandlers(...);
processEngineConfiguration.addEventHandler("myCustomType", new MyCustomEventHandler());

// ensure a handler exists before dispatching
if (processEngineConfiguration.getEventHandler(eventType) == null) {
    throw new IllegalStateException("No EventHandler registered for type " + eventType);
}

When it happens

Trigger: An EventSubscriptionEntity is delivered synchronously via eventReceived -> processEventSync, and processEngineConfiguration.getEventHandler(eventType) returns null because no EventHandler was registered for that subscription's getEventType().

Common situations: Custom event types registered in one engine node but not another; process definitions migrated from another BPMN engine that created subscription types this engine does not know; custom event subscription handling code that inserts subscriptions without registering handlers; classpath differences between cluster nodes.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• no org.flowable.app.engine.AppEngine defined in the applicat
• transactionManager is required property for SpringAppEngineC
• Setting a deployment name is not supported for apps
• couldn't initialize app engine from spring configuration res
• Failed to create property source

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