{"record":{"id":"7b55a9d3975440f2","repo":"flowable/flowable-engine","slug":"no-process-definition-found-for-key-processdefin","errorCode":null,"errorMessage":"No process definition found for key '{processDefinitionKey}'","messagePattern":"No process definition found for key '(.+?)'","errorType":"exception","errorClass":"FlowableObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessStartEventSubscriptionCmd.java","lineNumber":73,"sourceCode":"    protected void checkEventModelCorrelationParameter(EventModel eventModel, String correlationParameterName) {\n        Collection<EventPayload> correlationParameters = eventModel.getCorrelationParameters();\n        for (EventPayload correlationParameter : correlationParameters) {\n            if (correlationParameter.getName().equals(correlationParameterName)) {\n                return;\n            }\n        }\n        throw new FlowableIllegalArgumentException(\"There is no correlation parameter with name '\" + correlationParameterName + \"' defined in event model \"\n            + \"with key '\" + eventModel.getKey() + \"'. You can only subscribe for an event with a combination of valid correlation parameters.\");\n    }\n\n    protected ProcessDefinition getLatestProcessDefinitionByKey(String processDefinitionKey, String tenantId, CommandContext commandContext) {\n        ProcessDefinitionEntityManager processDefinitionEntityManager = CommandContextUtil.getProcessDefinitionEntityManager(commandContext);\n        ProcessDefinition processDefinition = null;\n        if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {\n            processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKey(processDefinitionKey);\n\n            if (processDefinition == null) {\n                throw new FlowableObjectNotFoundException(\"No process definition found for key '\" + processDefinitionKey + \"'\", ProcessDefinition.class);\n            }\n\n        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {\n\n            processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);\n\n            if (processDefinition == null) {\n                ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n                if (processEngineConfiguration.isFallbackToDefaultTenant()) {\n                    String defaultTenant = processEngineConfiguration.getDefaultTenantProvider().getDefaultTenant(tenantId, ScopeTypes.BPMN, processDefinitionKey);\n                    if (StringUtils.isNotEmpty(defaultTenant)) {\n                        processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, defaultTenant);\n                        \n                    } else {\n                        processDefinition = processDefinitionEntityManager.findLatestProcessDefinitionByKey(processDefinitionKey);\n                    }\n                    \n                    if (processDefinition == null) {","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessStartEventSubscriptionCmd.java#L55-L91","documentation":"Flowable throws this FlowableObjectNotFoundException when no process definition is deployed with the given process definition key (and no tenant filtering applies). The lookup in getLatestProcessDefinitionByKey queried the process definition entity manager and got null, so the operation requiring a definition (e.g. correlating a start message to a process) cannot proceed.","triggerScenarios":"Calling APIs built on AbstractProcessStartEventSubscriptionCmd (e.g. message/event start subscription correlation) with a processDefinitionKey that has no latest deployed definition, while tenantId is null or equals ProcessEngineConfiguration.NO_TENANT_ID.","commonSituations":"Typo in the process key; process definition never deployed; all definitions with that key were deleted from ACT_RE_PROCDEF; querying before deployment finished in another transaction/environment.","solutions":["Deploy a BPMN process definition whose process id equals the requested key before calling the API","Verify the exact key via repositoryService.createProcessDefinitionQuery().latestVersion().list() and correct the key string","Check you are not passing the process name or a different environment's key","If using tenants, pass the tenantId so the tenant-scoped lookup path is used"],"exampleFix":"// before\nruntimeService.createChangeActivityStateBuilder()... // correlation with key 'orderProcess' that was never deployed\n// after\nrepositoryService.createDeployment().addClasspathResource(\"order-process.bpmn20.xml\").deploy();\n// then use the same key as the BPMN <process id=\"orderProcess\">","handlingStrategy":"validation","validationCode":"long count = repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).count();\nif (count == 0) throw new IllegalStateException(\"Process definition key not deployed: \" + key);","typeGuard":null,"tryCatchPattern":"try {\n    // start/correlate by key\n} catch (FlowableObjectNotFoundException e) {\n    // log missing key, optionally auto-deploy, then rethrow or skip\n}","preventionTips":["Deploy all BPMN resources at application startup and assert query counts","Use constants for process keys instead of inline strings","Add an integration test correlating every process start key"],"tags":["flowable","process-definition","not-found","bpmn"],"backgroundTag":"resource-not-found","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"}