{"record":{"id":"aa8810e4ae3f984e","repo":"flowable/flowable-engine","slug":"no-process-definition-found-for-key-processdefin-aa8810","errorCode":null,"errorMessage":"No process definition found for key '<processDefinitionKey>'","messagePattern":"No process definition found for key '<processDefinitionKey>'","errorType":"exception","errorClass":"ActivitiObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceCmd.java","lineNumber":85,"sourceCode":"    }\n\n    @Override\n    public ProcessInstance execute(CommandContext commandContext) {\n        DeploymentManager deploymentManager = commandContext\n                .getProcessEngineConfiguration()\n                .getDeploymentManager();\n\n        // Find the process definition\n        ProcessDefinition processDefinition = null;\n        if (processDefinitionId != null) {\n            processDefinition = deploymentManager.findDeployedProcessDefinitionById(processDefinitionId);\n            if (processDefinition == null) {\n                throw new ActivitiObjectNotFoundException(\"No process definition found for id = '\" + processDefinitionId + \"'\", ProcessDefinition.class);\n            }\n        } else if (processDefinitionKey != null && (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId))) {\n            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKey(processDefinitionKey);\n            if (processDefinition == null) {\n                throw new ActivitiObjectNotFoundException(\"No process definition found for key '\" + processDefinitionKey + \"'\", ProcessDefinition.class);\n            }\n        } else if (processDefinitionKey != null && tenantId != null && !ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {\n            processDefinition = deploymentManager.findDeployedLatestProcessDefinitionByKeyAndTenantId(processDefinitionKey, tenantId);\n            if (processDefinition == null) {\n                throw new ActivitiObjectNotFoundException(\"No process definition found for key '\" + processDefinitionKey + \"' for tenant identifier \" + tenantId, ProcessDefinition.class);\n            }\n        } else {\n            throw new ActivitiIllegalArgumentException(\"processDefinitionKey and processDefinitionId are null\");\n        }\n\n        // Do not start process a process instance if the process definition is suspended\n        if (deploymentManager.isProcessDefinitionSuspended(processDefinition.getId())) {\n            throw new ActivitiException(\"Cannot start process instance. Process definition \"\n                    + processDefinition.getName() + \" (id = \" + processDefinition.getId() + \") is suspended\");\n        }\n\n        // Start the process instance\n        ExecutionEntity processInstance = ((ProcessDefinitionEntity) processDefinition).createProcessInstance(businessKey);","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceCmd.java#L67-L103","documentation":"Thrown by StartProcessInstanceCmd.execute() as ActivitiObjectNotFoundException when starting by key with no tenant (or the special NO_TENANT_ID) and no deployed process definition exists with that latest key. The engine looked up the latest definition by key and found nothing.","triggerScenarios":"RuntimeService.startProcessInstanceByKey(key) where the key is misspelled, the BPMN processId differs from the expected key, or no deployment containing that process was ever made to the default tenant.","commonSituations":"Deploying a BPMN file whose <process id=\"...\"> doesn't match the key used in code; forgetting to deploy the process definition before runtime use; deploying to a tenant but starting without tenantId; case mismatch in the key.","solutions":["Check the definition exists: RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).list() and fix the key if empty.","Ensure the BPMN process id (or key attribute) matches the key used in startProcessInstanceByKey.","Deploy the definition first (RepositoryService.createDeployment().addClasspathResource(...).deploy()).","If the definition is tenant-scoped, call startProcessInstanceByKey(key, tenantId) so the tenant-aware lookup runs."],"exampleFix":"// before\nruntimeService.startProcessInstanceByKey(\"OrderProcess\"); // wrong case, nothing deployed under this key\n// after\n// BPMN: <process id=\"orderProcess\" ...>\nruntimeService.startProcessInstanceByKey(\"orderProcess\");","handlingStrategy":"validation","validationCode":"if (repositoryService.createProcessDefinitionQuery()\n        .processDefinitionKey(definitionKey).count() == 0) {\n    throw new IllegalStateException(\"No definition deployed for key: \" + definitionKey);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return runtimeService.startProcessInstanceByKey(definitionKey, vars);\n} catch (ActivitiObjectNotFoundException e) {\n    log.error(\"Process definition key '{}' not deployed\", definitionKey, e);\n    throw new DeploymentMissingException(definitionKey, e);\n}","preventionTips":["Make deployment part of startup/tests so keys always exist before runtime use","Assert the BPMN <process id> equals the key string used in code","Add a smoke test that starts each process key in a test DB","Log available keys (ProcessDefinitionQuery list) when the lookup fails"],"tags":["process-definition","not-found","workflow","deployment"],"backgroundTag":"entity-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}