flowable/flowable-engine · error · FlowableIllegalArgumentException

At least one correlation parameter value must be provided fo

Error message

At least one correlation parameter value must be provided for a dynamic process start event subscription, otherwise the process would get started on all events, regardless their correlation parameter values.

What it means

checkValidInformation also requires at least one correlation parameter value; without one, every incoming start event would trigger a new process instance, which Flowable forbids. It throws FlowableIllegalArgumentException when correlationParameterValues is empty at subscribe() time.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/runtime/ProcessInstanceStartEventSubscriptionBuilderImpl.java:98

    }

    public String getTenantId() {
        return tenantId;
    }

    @Override
    public EventSubscription subscribe() {
        checkValidInformation();
        return runtimeService.registerProcessInstanceStartEventSubscription(this);
    }

    protected void checkValidInformation() {
        if (StringUtils.isEmpty(processDefinitionKey)) {
            throw new FlowableIllegalArgumentException("The process definition must be provided using the key for the subscription to be registered.");
        }

        if (correlationParameterValues.isEmpty()) {
            throw new FlowableIllegalArgumentException(
                "At least one correlation parameter value must be provided for a dynamic process start event subscription, "
                    + "otherwise the process would get started on all events, regardless their correlation parameter values.");
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add at least one .correlationValue(name, value) (or correlation values map) before subscribe().
2. Validate the correlation map is non-empty at startup and fail fast with a clear message.
3. Ensure the event payload fields used for correlation are actually populated.

Example fix

// before
Map<String, Object> corr = extractCorrelations(event); // may be empty
var b = runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
    .processDefinitionKey("orderProcess");
corr.forEach(b::correlationValue);
b.subscribe(); // throws when empty
// after
Map<String, Object> corr = extractCorrelations(event);
if (corr.isEmpty()) {
    throw new IllegalStateException("No correlation values for start subscription");
}
var b = runtimeService.createProcessInstanceStartEventSubscriptionBuilder()
    .processDefinitionKey("orderProcess");
corr.forEach(b::correlationValue);
b.subscribe();

if (correlationValues == null || correlationValues.isEmpty()) throw new IllegalArgumentException("at least one correlation value required");

boolean hasCorrelations(Map<String, Object> m) { return m != null && !m.isEmpty(); }

try {
    subscriptionBuilder.subscribe();
} catch (FlowableIllegalArgumentException e) {
    log.error("Subscription rejected: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Calling subscribe() without any correlationValue(...) calls; passing an empty map; all correlation values set conditionally and skipped at runtime.

Common situations: Event-driven start scenarios where correlation data depends on payload fields that were absent; examples followed incompletely; generic subscription builders parameterized with dynamic (possibly empty) correlation sets.

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

• At least one correlation parameter value must be provided fo
• The process definition must be provided using the key for th
• The case definition must be provided using the key for the s
• The case definition must be provided using the exact id of t
• The case definition must be provided using the exact id of t

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