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 case start event subscription, otherwise the case would get started on all events, regardless their correlation parameter values.

What it means

CaseInstanceStartEventSubscriptionBuilderImpl.checkValidInformation() requires at least one correlation parameter value for a dynamic case start event subscription. Without one, the case would start on every matching event regardless of payload, which Flowable rejects with FlowableIllegalArgumentException.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceStartEventSubscriptionBuilderImpl.java:97

    }

    public String getTenantId() {
        return tenantId;
    }

    @Override
    public EventSubscription subscribe() {
        checkValidInformation();
        return cmmnRuntimeService.registerCaseInstanceStartEventSubscription(this);
    }

    protected void checkValidInformation() {
        if (StringUtils.isEmpty(caseDefinitionKey)) {
            throw new FlowableIllegalArgumentException("The case 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 case start event subscription, "
                    + "otherwise the case would get started on all events, regardless their correlation parameter values.");
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add at least one correlationParameterValue/correlationParameters entry before subscribe()
2. Derive the correlation values from the event payload mapping configured in the CMMN model
3. If unconditional start is intended, use static (non-dynamic) case start behavior instead of a start event subscription

Example fix

// before
builder.caseDefinitionKey("myCase").subscribe(); // no correlation values
// after
builder.caseDefinitionKey("myCase")
    .correlationParameterValue("orderId", orderId)
    .subscribe();

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

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

try { builder.subscribe(); } catch (FlowableIllegalArgumentException e) { log.error("Missing correlation parameter values: {}", e.getMessage()); }

When it happens

Trigger: Building a subscription via createCaseInstanceStartEventSubscriptionBuilder().caseDefinitionKey(...) then subscribe() without adding any correlation parameter value (correlationParameterValues map empty).

Common situations: Omitting correlationParameter(name, value) calls; passing an empty map via the bulk API; assuming correlation parameters are optional because start forms are optional.

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

• 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
• At least one correlation parameter value must be provided fo
• There is no correlation parameter with name '${correlationPa

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