flowable/flowable-engine · error · FlowableException

Could not resolve key for: ${eventDefinitionKey} for ${execu

Error message

Could not resolve key for: ${eventDefinitionKey} for ${executionEntity}

What it means

Thrown by ReceiveEventTaskActivityBehavior.getEventDefinitionKey when a receive event task cannot determine the event definition key to listen for. The key comes from the event definition reference or an expression; if both resolution paths yield null, Flowable cannot know which event to wait for and aborts with this exception.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/ReceiveEventTaskActivityBehavior.java:120

                CountingEntityUtil.handleDeleteEventSubscriptionEntityCount(eventSubscription);
            }
        }

        super.leave(execution);
    }

    protected String getEventDefinitionKey(CommandContext commandContext, ExecutionEntity executionEntity) {
        Object key = null;

        if (StringUtils.isNotEmpty(eventDefinitionKey)) {
            Expression expression = CommandContextUtil.getProcessEngineConfiguration(commandContext)
                .getExpressionManager()
                .createExpression(eventDefinitionKey);
            key = expression.getValue(executionEntity);
        }

        if (key == null) {
            throw new FlowableException("Could not resolve key for: " + eventDefinitionKey + " for " + executionEntity);
        }

        return key.toString();
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Check the receive event task's eventDefinition reference in the BPMN XML and ensure it matches a deployed event definition key
Deploy the missing event definition to the event registry before starting the process
If an expression is used for the event definition key, ensure the referenced variable is populated before the activity executes
Log the value of the eventDefinitionKey expression on a test execution to confirm what it evaluates to

Example fix

// before
<receiveEvent eventDefinition="${unboundVar}"/>
// after
<receiveEvent eventDefinition="orderReceivedEvent"/>

Defensive patterns

Strategy: validation

Validate before calling

// Before deploying/starting: confirm the referenced event definition exists
EventRepositoryService ers = CommandContextUtil.getEventRepositoryService(commandContext);
if (ers.getEventModelByKey(eventKey, tenantId) == null) {
    throw new IllegalStateException("Event definition not deployed: " + eventKey);
}

Try / catch

try {
    runtimeService.signalEventReceived(eventKey, executionId);
} catch (FlowableException e) {
    // resolve key / deploy missing event definition
}

Prevention

Keep event definitions in the same deployment unit as the process
Validate eventDefinition refs at deploy time with a process validation listener
Avoid unbounded expressions as event definition keys

When it happens

Trigger: A receive event task (or boundary/intermediate catch event) whose eventDefinition key cannot be resolved: the referenced event definition is missing/empty in the BPMN XML, or a dynamic expression used as the event definition key evaluates to null at runtime.

Common situations: Typos in the eventDefinition ref attribute, deploying a process that references an event definition that was never deployed to the event registry, or an expression that yields null because an input variable was not set.

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

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