flowable/flowable-engine · error · FlowableIllegalArgumentException

There is no correlation parameter with name '{correlationPar

Error message

There is no correlation parameter with name '{correlationParameterName}' defined in event model with key '{eventModel.getKey()}'. You can only subscribe for an event with a combination of valid correlation parameters.

What it means

When subscribing a process to a process start event, AbstractProcessStartEventSubscriptionCmd validates each supplied correlation parameter against the event model (event registry) definition. A correlationParameterName that is not declared in the event model's correlation parameters causes this FlowableIllegalArgumentException, preventing an impossible subscription.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessStartEventSubscriptionCmd.java:62

        EventModel eventModel = getEventModel(eventDefinitionKey, tenantId, commandContext);
        Map<String, Object> correlationParameters = new HashMap<>();
        for (Map.Entry<String, Object> correlationValue : correlationParameterValues.entrySet()) {
            // make sure the correlation parameter value is based on a valid, defined correlation parameter within the event model
            checkEventModelCorrelationParameter(eventModel, correlationValue.getKey());
            correlationParameters.put(correlationValue.getKey(), correlationValue.getValue());
        }

        return CommandContextUtil.getEventRegistry().generateKey(correlationParameters);
    }

    protected void checkEventModelCorrelationParameter(EventModel eventModel, String correlationParameterName) {
        Collection<EventPayload> correlationParameters = eventModel.getCorrelationParameters();
        for (EventPayload correlationParameter : correlationParameters) {
            if (correlationParameter.getName().equals(correlationParameterName)) {
                return;
            }
        }
        throw new FlowableIllegalArgumentException("There is no correlation parameter with name '" + correlationParameterName + "' defined in event model "
            + "with key '" + eventModel.getKey() + "'. You can only subscribe for an event with a combination of valid correlation parameters.");
    }

    protected ProcessDefinition getLatestProcessDefinitionByKey(String processDefinitionKey, String tenantId, CommandContext commandContext) {
        ProcessDefinitionEntityManager processDefinitionEntityManager = CommandContextUtil.getProcessDefinitionEntityManager(commandContext);
        ProcessDefinition processDefinition = null;
        if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {
            processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKey(processDefinitionKey);

            if (processDefinition == null) {
                throw new FlowableObjectNotFoundException("No process definition found for key '" + processDefinitionKey + "'", ProcessDefinition.class);
            }

        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {

            processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);

            if (processDefinition == null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Align the correlation parameter names in the subscription call with the deployed event model definition (fix spelling or use the current parameter names).
2. Update the event model to declare the correlation parameter the code expects, then redeploy the event definition.
3. Verify the eventModel key being targeted — the parameter may exist on a different event model than the one resolved.

Example fix

// before
builder.correlationParameter("orderIdold"); // not defined in event model
// after
builder.correlationParameter("orderId"); // matches event model correlation parameter

Set<String> valid = eventModel.getCorrelationParameters().stream()
    .map(EventPayload::getName).collect(Collectors.toSet());
if (!valid.contains(correlationParameterName)) {
    throw new IllegalArgumentException("Unknown correlation parameter " + correlationParameterName);
}

When it happens

Trigger: Calling createProcessInstanceStartEventSubscriptionServiceCmd / runtimeService event-registry subscription APIs with a correlation parameter name not present in eventModel.getCorrelationParameters() for the given event model key — typically a typo or a parameter removed from the event definition while old subscription code still sends it.

Common situations: Event model (JSON/BPMN event registry definition) updated to rename or drop a correlation parameter while client code still uses the old name; typo between the deployment and the subscription call; wrong event key passed so the looked-up model lacks the parameter.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• At least one correlation parameter value must be provided fo
• EventRegistryEventDefinition on '" + elementId + "' has an e
• At least one correlation parameter value must be provided fo
• A channel key detection value is required for the channel mo
• The channel json key detection value was not found for the c

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