{"record":{"id":"0c88f1406120919a","repo":"flowable/flowable-engine","slug":"no-process-definition-found-for-key-processdefi","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/util/ProcessInstanceHelper.java","lineNumber":423,"sourceCode":"                } else {\n                    processDefinition = processDefinitionEntityManager\n                            .findLatestProcessDefinitionByKey(processDefinitionKey);\n                }\n            }\n        } else {\n            if (parentDeploymentId != null) {\n                processDefinition = processDefinitionEntityManager\n                        .findProcessDefinitionByParentDeploymentAndKey(parentDeploymentId, processDefinitionKey);\n            }\n            if (processDefinition == null) {\n                processDefinition = processDefinitionEntityManager\n                        .findLatestProcessDefinitionByKey(processDefinitionKey);\n            }\n        }\n\n        if (processDefinition == null) {\n            if (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {\n                throw new FlowableObjectNotFoundException(\n                        \"No process definition found for key '\" + processDefinitionKey + \"'\", ProcessDefinition.class);\n            } else if (fallbackToDefaultTenant) {\n                throw new FlowableObjectNotFoundException(\n                        \"No process definition found for key '\" + processDefinitionKey + \"'. Fallback to default tenant was also applied.\", ProcessDefinition.class);\n            } else {\n                throw new FlowableObjectNotFoundException(\n                        \"Process definition with key '\" + processDefinitionKey + \"' and tenantId '\" + tenantId + \"' was not found\", ProcessDefinition.class);\n            }\n        }\n\n        return processDefinition;\n    }\n\n    public void callCaseInstanceStateChangeCallbacks(CommandContext commandContext, ProcessInstance processInstance, String oldState, String newState) {\n        if (processInstance.getCallbackId() != null && processInstance.getCallbackType() != null) {\n            Map<String, List<RuntimeInstanceStateChangeCallback>> caseInstanceCallbacks = CommandContextUtil\n                    .getProcessEngineConfiguration(commandContext).getProcessInstanceStateChangedCallbacks();\n","sourceCodeStart":405,"sourceCodeEnd":441,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/ProcessInstanceHelper.java#L405-L441","documentation":"A FlowableObjectNotFoundException thrown by resolveProcessDefinition when no ProcessDefinition entity exists for the given key (with the given tenant, or no tenant). This is the no-tenant / NO_TENANT_ID branch of the three-way lookup failure in ProcessInstanceHelper.","triggerScenarios":"RuntimeService.startProcessInstanceByKey(key, ...) (including message/signal paths) when findLatestProcessDefinitionByKey returns null — the process was never deployed, the key is misspelled, or the key only exists under a tenant id while none was supplied.","commonSituations":"Deploying to a tenant-aware engine but calling without tenantId; typo in the key vs the <process id=\"...\">; environment (test vs prod) where the process was never deployed; engine started against an empty/fresh database.","solutions":["Deploy the BPMN file: repositoryService.createDeployment().addClasspathResource(\"...bpmn20.xml\").deploy().","Verify the key equals the <process id=\"...\"> attribute via a ProcessDefinitionQuery on processDefinitionKey.","If the process is tenant-scoped, call the startProcessInstance...ByKey overload with the correct tenantId.","Confirm you are connected to the database/environment where the definition exists."],"exampleFix":"// before\nruntimeService.startProcessInstanceByKey(\"orderProcess\", vars); // never deployed\n// after\nrepositoryService.createDeployment().addClasspathResource(\"processes/order-process.bpmn20.xml\").tenantId(\"acme\").deploy();\nruntimeService.startProcessInstanceByKey(\"orderProcess\", \"acme\", vars);","handlingStrategy":"validation","validationCode":"ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult();\nif (def == null) {\n    throw new IllegalStateException(\"Process '\" + key + \"' not deployed — deploy the BPMN resource before starting\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return runtimeService.startProcessInstanceByKey(key, vars);\n} catch (FlowableObjectNotFoundException e) {\n    if (e.getMessage().startsWith(\"No process definition found for key\")) {\n        repositoryService.createDeployment().addClasspathResource(\"processes/\" + key + \".bpmn20.xml\").deploy();\n        return runtimeService.startProcessInstanceByKey(key, vars);\n    }\n    throw e;\n}","preventionTips":["Add a startup readiness check that queries required process definition keys","Keep process keys as constants, never inline strings","Verify deployment in CI before releasing services that start instances","Confirm the datasource points at the intended environment"],"tags":["bpmn","process-definition","tenant","not-found","flowable"],"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"}