flowable/flowable-engine · error · FlowableException

Could not resolve key for: ${eventDefinitionKey} in ${execut

Error message

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

What it means

Flowable throws this in BoundaryEventRegistryEventActivityBehavior.getEventDefinitionKey when the event registry event definition key cannot be resolved to an actual value. The key can be a fixed string or an expression; when it is null after static resolution and expression evaluation against the execution, the behavior cannot subscribe to the registry event and aborts. This means the configured key is empty/blank or the expression evaluated to null.

Source

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

                    CountingEntityUtil.handleDeleteEventSubscriptionEntityCount(eventSubscription);
                }
            }
        }

        super.trigger(executionEntity, triggerName, triggerData);
    }

    protected String getEventDefinitionKey(ExecutionEntity executionEntity, ProcessEngineConfigurationImpl processEngineConfiguration) {
        Object key = null;

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

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

        return key.toString();
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Ensure the variable used in the key expression is set (correlation-initiating or via an execution listener) before the flow reaches the boundary event.
Check the event key configured on the boundary event definition in the BPMN XML / modeler is non-empty.
Test the expression independently (e.g. log ${eventKey}) to see what it evaluates to.
If the key should be static, replace the expression with a literal event key string registered in the event registry.

Example fix

// before (expression may be null)
<flowable:eventDefinitionKey>${missingEventKey}</flowable:eventDefinitionKey>

// after (set variable before the boundary event, or use a static key)
<flowable:eventDefinitionKey>order-cancelled-event</flowable:eventDefinitionKey>

Defensive patterns

Strategy: validation

Validate before calling

// before reaching the boundary event, guarantee the key variable exists
execution.setVariable("orderCancelledEventKey", "order-cancelled-event");
// or validate before start:
if (variables.get("orderCancelledEventKey") == null) {
    throw new IllegalArgumentException("orderCancelledEventKey must be set for event registry boundary event");
}

Type guard

boolean hasEventKey(DelegateExecution execution, String varName) {
    Object v = execution.getVariable(varName);
    return v instanceof String && !((String) v).isBlank();
}

Try / catch

try {
    runtimeService.startProcessInstanceByKey("myProcess", variables);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Could not resolve key for")) {
        // set the missing event-key variable or correct the expression
    }
}

Prevention

Initialize all event-registry key variables at process start via a start listener or start form.
Prefer static literal keys over expressions unless dynamic correlation is truly required.
Add a unit test asserting the key expression resolves to a non-null string before deployment.

When it happens

Trigger: A boundary event with a registry (event-registry) event definition whose key attribute is empty, or whose key expression (e.g. ${eventKey}) resolves to null because the referenced process variable is unset at the time the execution reaches the boundary event.

Common situations: Forgetting to set the process variable used in the key expression before reaching the boundary event; a typo in the variable name inside the expression; deploying a model where the event-registry key was never configured; case-sensitivity issues in variable names.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — 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/8f115242005fccbb. Report an issue: GitHub.