{"record":{"id":"3be213fb79011b8f","repo":"flowable/flowable-engine","slug":"no-process-definition-found-for-id-processdefi","errorCode":null,"errorMessage":"No process definition found for id = '<processDefinitionId>'","messagePattern":"No process definition found for id = '<processDefinitionId>'","errorType":"exception","errorClass":"ActivitiObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceCmd.java","lineNumber":80,"sourceCode":"                processInstanceBuilder.getBusinessKey(),\n                processInstanceBuilder.getVariables(),\n                processInstanceBuilder.getTenantId());\n        this.processInstanceName = processInstanceBuilder.getProcessInstanceName();\n        this.transientVariables = processInstanceBuilder.getTransientVariables();\n    }\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 \"","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/StartProcessInstanceCmd.java#L62-L98","documentation":"Thrown by StartProcessInstanceCmd.execute() as ActivitiObjectNotFoundException when a process definition id is supplied but no deployed definition with that id exists in the deployment cache/repository. The engine cannot locate the definition needed to instantiate a new process instance, and ProcessDefinition.class is attached as the missing object type.","triggerScenarios":"RuntimeService.startProcessInstanceById(badId) where the id is wrong, malformed, belongs to another engine/database, or the deployment was deleted; stale ids persisted in application data pointing to an undeployed definition.","commonSituations":"Copying a definition id from a different environment (test vs prod) or different database schema; definition deleted via RepositoryService.deleteDeployment while callers still reference its id; pointing at a shared DB where another engine's definitions live.","solutions":["Query the actual id with RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult() and use that id.","Prefer starting by key (startProcessInstanceByKey) so the latest active version is resolved automatically.","Verify the definition exists in the connected DB/schema and that the engine points at the right database and tenant.","Fix application data holding stale definition ids; re-resolve ids after each redeploy since versions/ids change."],"exampleFix":"// before\nruntimeService.startProcessInstanceById(\"orderProcess:1:hardcoded-id\", vars); // stale id\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(\"orderProcess\").latestVersion().singleResult();\nruntimeService.startProcessInstanceById(pd.getId(), vars);","handlingStrategy":"validation","validationCode":"ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionId(definitionId).singleResult();\nif (pd == null) {\n    throw new IllegalStateException(\"Unknown process definition id: \" + definitionId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return runtimeService.startProcessInstanceById(definitionId, vars);\n} catch (ActivitiObjectNotFoundException e) {\n    // check missing object type and fall back to key lookup\n    if (ProcessDefinition.class.equals(e.getObjectClass())) {\n        return runtimeService.startProcessInstanceByKey(knownKey, vars);\n    }\n    throw e;\n}","preventionTips":["Never hardcode definition ids — always resolve via ProcessDefinitionQuery","Prefer startProcessInstanceByKey so version changes don't break callers","Re-resolve ids after every deployment or deleteDeployment","Verify both engines point at the same database when sharing ids across environments"],"tags":["process-definition","not-found","workflow","repository"],"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"}