{"record":{"id":"b9815ebf613951c7","repo":"flowable/flowable-engine","slug":"the-case-definition-must-be-provided-using-the-key","errorCode":null,"errorMessage":"The case definition must be provided using the key for the subscription to be registered.","messagePattern":"The case definition must be provided using the key for the subscription to be registered\\.","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceStartEventSubscriptionBuilderImpl.java","lineNumber":93,"sourceCode":"    }\n\n    public boolean isDoNotUpdateToLatestVersionAutomatically() {\n        return doNotUpdateToLatestVersionAutomatically;\n    }\n\n    public String getTenantId() {\n        return tenantId;\n    }\n\n    @Override\n    public EventSubscription subscribe() {\n        checkValidInformation();\n        return cmmnRuntimeService.registerCaseInstanceStartEventSubscription(this);\n    }\n\n    protected void checkValidInformation() {\n        if (StringUtils.isEmpty(caseDefinitionKey)) {\n            throw new FlowableIllegalArgumentException(\"The case definition must be provided using the key for the subscription to be registered.\");\n        }\n\n        if (correlationParameterValues.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\n                \"At least one correlation parameter value must be provided for a dynamic case start event subscription, \"\n                    + \"otherwise the case would get started on all events, regardless their correlation parameter values.\");\n        }\n    }\n}\n","sourceCodeStart":75,"sourceCodeEnd":103,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceStartEventSubscriptionBuilderImpl.java#L75-L103","documentation":"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.","triggerScenarios":"Calling cmmnRuntimeService.createCaseInstanceStartEventSubscriptionBuilder() and then subscribe() without ever calling caseDefinitionKey(String), or passing null/empty string to it.","commonSituations":"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.","solutions":["Call caseDefinitionKey(\"myCase\") with a non-empty key before subscribe()","Verify the case definition with that key is deployed (deployedKey lookup) and the config value is not blank","Check builder call chain order so the key is set before subscribe()"],"exampleFix":"// before\nruntimeService.createCaseInstanceStartEventSubscriptionBuilder()\n    .correlationParameterValue(...)\n    .subscribe(); // missing caseDefinitionKey\n// after\nruntimeService.createCaseInstanceStartEventSubscriptionBuilder()\n    .caseDefinitionKey(\"myCaseDefinitionKey\")\n    .correlationParameterValue(...)\n    .subscribe();","handlingStrategy":"validation","validationCode":"if (caseDefinitionKey == null || caseDefinitionKey.isEmpty()) throw new IllegalStateException(\"caseDefinitionKey required before subscribe()\");","typeGuard":"boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }","tryCatchPattern":"try { builder.subscribe(); } catch (FlowableIllegalArgumentException e) { log.error(\"Subscription setup invalid: {}\", e.getMessage()); }","preventionTips":["Set caseDefinitionKey immediately after obtaining the builder","Validate config-sourced keys are non-blank at startup","Wrap builder setup in a helper that enforces required fields"],"tags":["flowable","cmmn","event-subscription","validation","missing-key"],"backgroundTag":"missing-required-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}