Activiti/Activiti · error · ActivitiException

Could not find eventhandler for event of type

Error message

Could not find eventhandler for event of type '${eventSubscriptionEntity.getEventType()}'.

What it means

Activiti throws this ActivitiException when an event subscription fires but no EventHandler is registered in the ProcessEngineConfiguration for that event's type. processEventSync looks up the handler from the eventHandlers map and aborts when it is null. It means the engine encountered an event type (e.g. a custom signal/message event or signal created at runtime) that has no handler wired.

Solutions

1. Register an EventHandler for the type in ProcessEngineConfiguration (setEventHandlers / addEventHandler / custom EventHandlerFactory covering the event type).
2. Log eventSubscriptionEntity.getEventType() at the failure point and confirm what type is actually flowing through.
3. If it is a standard signal/message, do not create EventSubscriptionEntity rows manually — use runtimeService APIs so the engine wires the right handlers.
4. After an upgrade, review activiti event handler configuration against the new version's handler classes.

Object handler = ProcessEngines.getDefaultProcessEngine()
    .getProcessEngineConfiguration().getEventHandlers().get(eventType);
if (handler == null) throw new IllegalStateException("No EventHandler registered for " + eventType);

try {
    runtimeService.signalEventReceived(signalName, payload);
} catch (org.activiti.engine.ActivitiException e) {
    if (e.getMessage().startsWith("Could not find eventhandler")) {
        log.error("Missing EventHandler for signal {}", signalName, e);
    }
    throw e;
}

When it happens

Trigger: eventReceived/processEventSync processing an EventSubscriptionEntity whose getEventType() is not present in processEngineConfiguration.getEventHandlers() — e.g. custom event types, signals dispatched via runtimeService.signalEventReceived with an unknown type, or handlers removed from config.

Common situations: Custom event subscriptions added programmatically without registering a matching EventHandlerFactory in config; upgrade to a newer Activiti where a built-in handler class was renamed/removed; typo in event type string when creating the subscription.

Related errors

• A numeric value between 1 and 5 must follow the '#' option
• Activiti database problem
• businessCalendars can not be null
• '?' can only be specified for Day-of-Month -OR- Day-of-Week.
• '?' can only be specified for Day-of-Month or Day-of-Week.

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/dcb715aca77faf7c. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/persistence/entity/EventSubscriptionEntityManagerImpl.java:347

    public void eventReceived(EventSubscriptionEntity eventSubscriptionEntity, Object payload, boolean processASync) {
        if (processASync) {
            scheduleEventAsync(eventSubscriptionEntity, payload);
        } else {
            processEventSync(eventSubscriptionEntity, payload);
        }
    }

    protected void processEventSync(EventSubscriptionEntity eventSubscriptionEntity, Object payload) {
        // A compensate event needs to be deleted before the handlers are called
        if (eventSubscriptionEntity instanceof CompensateEventSubscriptionEntity) {
            delete(eventSubscriptionEntity);
        }

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

    protected void scheduleEventAsync(EventSubscriptionEntity eventSubscriptionEntity, Object payload) {
        JobEntity message = getJobEntityManager().create();
        message.setJobType(JobEntity.JOB_TYPE_MESSAGE);
        message.setJobHandlerType(ProcessEventJobHandler.TYPE);
        message.setJobHandlerConfiguration(eventSubscriptionEntity.getId());
        message.setTenantId(eventSubscriptionEntity.getTenantId());

        // TODO: support payload
        // if(payload != null) {
        // message.setEventPayload(payload);
        // }

View on GitHub (pinned to 56435b1a97)