flowable/flowable-engine · error · FlowableException

Could not find matching FlowElement for " + eventSubscriptio

Error message

Could not find matching FlowElement for " + eventSubscription

What it means

When a signal targets a signal start event, SignalEventHandler looks up the flow element in the BPMN model by the subscription's activityId. If the model contains no matching element, this error is thrown, meaning the event subscription points at an element that no longer exists in the deployed process definition.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/event/SignalEventHandler.java:61

    public void handleEvent(EventSubscriptionEntity eventSubscription, Object payload, CommandContext commandContext) {
        if (eventSubscription.getExecutionId() != null) {
            super.handleEvent(eventSubscription, payload, commandContext);

        } else if (eventSubscription.getProcessDefinitionId() != null) {

            // Find initial flow element matching the signal start event
            String processDefinitionId = eventSubscription.getProcessDefinitionId();
            org.flowable.bpmn.model.Process process = ProcessDefinitionUtil.getProcess(processDefinitionId);
            ProcessDefinition processDefinition = ProcessDefinitionUtil.getProcessDefinition(processDefinitionId);

            if (processDefinition.isSuspended()) {
                throw new FlowableException("Could not handle signal: process definition with id: " + processDefinitionId + " is suspended for " + eventSubscription);
            }

            // Start process instance via the flow element linked to the event
            FlowElement flowElement = process.getFlowElement(eventSubscription.getActivityId(), true);
            if (flowElement == null) {
                throw new FlowableException("Could not find matching FlowElement for " + eventSubscription);
            }

            ProcessInstanceHelper processInstanceHelper = CommandContextUtil.getProcessEngineConfiguration(commandContext).getProcessInstanceHelper();
            processInstanceHelper.createAndStartProcessInstanceWithInitialFlowElement(processDefinition, null, null, null, flowElement, process,
                    getPayloadAsMap(payload), null, null, null, true);

        } else if (eventSubscription.getScopeId() != null && ScopeTypes.CMMN.equals(eventSubscription.getScopeType())) {
            CommandContextUtil.getProcessEngineConfiguration(commandContext).getCaseInstanceService().handleSignalEvent(eventSubscription, getPayloadAsMap(payload));
        
        } else {
            throw new FlowableException("Invalid signal handling: no execution nor process definition set for " + eventSubscription);
        }
    }

    protected Map<String, Object> getPayloadAsMap(Object payload) {
        Map<String, Object> variables = null;
        if (payload instanceof Map) {
            variables = (Map<String, Object>) payload;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Compare the subscription's ACTIVITY_ID_ (ACT_RU_EVENT_SUBSCR) with the signal start event id in the deployed BPMN XML; fix/redeploy the model.
2. Delete the stale event subscription (runtimeService.deleteEventSubscription / createEventRegistryEventSubscriptionQuery) or cancel the orphaned definition.
3. Redeploy the original BPMN that contains the referenced start event id.
4. Restart the node(s) to refresh the process definition cache if the model was just redeployed.

Example fix

// before
// renamed start signal event id from 'signalStart' to 'signalStart2' in BPMN, subscription stale
// after
// keep element ids stable across redeploys, or cleanup:
for (EventSubscription sub : runtimeService.createEventSubscriptionQuery()
        .eventName("orderSignal").list()) {
    // verify each subscription's activityId exists in the current model before signaling
}

org.flowable.bpmn.model.Process p = ProcessDefinitionUtil.getProcess(sub.getProcessDefinitionId());
if (p.getFlowElement(sub.getActivityId(), true) == null) {
    throw new IllegalStateException("Stale subscription: activity " + sub.getActivityId() + " not in model");
}

try {
    runtimeService.signalEventReceived(signalName);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Could not find matching FlowElement")) {
        cleanupStaleSubscription(signalName);
    } else { throw e; }
}

When it happens

Trigger: signalEventReceived/dispatchEvent for a start-event subscription whose activityId is absent from process.getFlowElement(activityId, true) — typically after the definition was changed/redeployed while old subscriptions remained, or a corrupted event subscription row.

Common situations: Redeploying an updated BPMN where the signal start event id was renamed/deleted, database restore mismatching ACT_RU_EVENT_SUBSCR with ACT_GE_BYTEARRAY model data, cache staleness after multi-node deployment.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Cannot throw process-instance scoped signal, since the dispa
• Could not handle signal: process definition with id: " + pro
• Invalid signal handling: no execution nor process definition
• BPMN XSD could not be found
• The bpmn 2.0 xml is not properly encoded

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