{"record":{"id":"3107e9660c7e6e0a","repo":"flowable/flowable-engine","slug":"the-process-definition-must-be-provided-using-the","errorCode":null,"errorMessage":"The process definition must be provided using the key for the subscription to be registered.","messagePattern":"The process definition must be provided using the key for the subscription to be registered\\.","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/runtime/ProcessInstanceStartEventSubscriptionBuilderImpl.java","lineNumber":94,"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 runtimeService.registerProcessInstanceStartEventSubscription(this);\n    }\n\n    protected void checkValidInformation() {\n        if (StringUtils.isEmpty(processDefinitionKey)) {\n            throw new FlowableIllegalArgumentException(\"The process 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 process start event subscription, \"\n                    + \"otherwise the process would get started on all events, regardless their correlation parameter values.\");\n        }\n    }\n}\n","sourceCodeStart":76,"sourceCodeEnd":104,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/runtime/ProcessInstanceStartEventSubscriptionBuilderImpl.java#L76-L104","documentation":"ProcessInstanceStartEventSubscriptionBuilderImpl.subscribe() validates its configuration via checkValidInformation before registering a start-event subscription. A subscription must know which process definition (by key) to start; an empty/null processDefinitionKey throws FlowableIllegalArgumentException.","triggerScenarios":"Building a subscription with runtimeService.createProcessInstanceStartEventSubscriptionBuilder() and setting correlation values but never calling processDefinitionKey(...) before subscribe(); setting the key to an empty string or null variable.","commonSituations":"Dynamic subscription setup where the key is loaded from configuration that was missing; refactoring that renamed the setter call away; copying example code that only sets correlation parameters.","solutions":["Call .processDefinitionKey(\"yourProcessKey\") on the builder before subscribe().","Validate the configured key is non-empty at application startup.","Ensure the config source actually supplies the key (check properties/yml for nulls)."],"exampleFix":"// before\nruntimeService.createProcessInstanceStartEventSubscriptionBuilder()\n    .correlationValue(\"orderId\", orderId)\n    .subscribe(); // no process definition key\n// after\nruntimeService.createProcessInstanceStartEventSubscriptionBuilder()\n    .processDefinitionKey(\"orderProcess\")\n    .correlationValue(\"orderId\", orderId)\n    .subscribe();","handlingStrategy":"validation","validationCode":"if (processDefinitionKey == null || processDefinitionKey.isBlank()) throw new IllegalArgumentException(\"processDefinitionKey required\");","typeGuard":"boolean hasKey(String k) { return k != null && !k.isBlank(); }","tryCatchPattern":"try {\n    subscriptionBuilder.subscribe();\n} catch (FlowableIllegalArgumentException e) {\n    log.error(\"Invalid start-event subscription config: {}\", e.getMessage());\n    throw e;\n}","preventionTips":["Always set processDefinitionKey first when composing the builder.","Externalize the key to config and validate at startup.","Add an integration test that registers subscriptions with production config."],"tags":["java","flowable","event-subscription","validation","missing-argument"],"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"}