flowable/flowable-engine · error · FlowableIllegalArgumentException

The case definition must be provided using the key for the s

Error message

The case definition must be provided using the key for the subscription to be registered.

What it means

CaseInstanceStartEventSubscriptionBuilderImpl.subscribe() calls checkValidInformation() before registering a dynamic case start event subscription. A subscription must target a case definition by key; if caseDefinitionKey is empty or null, registration is impossible, so a FlowableIllegalArgumentException is thrown.

Source

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

    }

    public boolean isDoNotUpdateToLatestVersionAutomatically() {
        return doNotUpdateToLatestVersionAutomatically;
    }

    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. Call caseDefinitionKey("myCase") with a non-empty key before subscribe()
2. Verify the case definition with that key is deployed (deployedKey lookup) and the config value is not blank
3. Check builder call chain order so the key is set before subscribe()

Example fix

// before
runtimeService.createCaseInstanceStartEventSubscriptionBuilder()
    .correlationParameterValue(...)
    .subscribe(); // missing caseDefinitionKey
// after
runtimeService.createCaseInstanceStartEventSubscriptionBuilder()
    .caseDefinitionKey("myCaseDefinitionKey")
    .correlationParameterValue(...)
    .subscribe();

if (caseDefinitionKey == null || caseDefinitionKey.isEmpty()) throw new IllegalStateException("caseDefinitionKey required before subscribe()");

boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }

try { builder.subscribe(); } catch (FlowableIllegalArgumentException e) { log.error("Subscription setup invalid: {}", e.getMessage()); }

When it happens

Trigger: Calling cmmnRuntimeService.createCaseInstanceStartEventSubscriptionBuilder() and then subscribe() without ever calling caseDefinitionKey(String), or passing null/empty string to it.

Common situations: Forgetting to set the case definition key on the builder; the key coming from config/properties that were blank; copying builder code that sets only correlation parameter values.

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 exact id of t
• At least one correlation parameter value must be provided fo
• The case definition must be provided using the exact id of t
• There is no correlation parameter with name '${correlationPa
• type is required when adding a new case instance identity li

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