{"record":{"id":"300add2d996cb4a5","repo":"flowable/flowable-engine","slug":"cannot-find-process-definition-for-id-processdef","errorCode":null,"errorMessage":"Cannot find process definition for id '{processDefinitionId}'","messagePattern":"Cannot find process definition for id '(.+?)'","errorType":"exception","errorClass":"FlowableObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java","lineNumber":123,"sourceCode":"        // If process definition is already provided (eg. when command is called through the DeployCmd)\r\n        // we don't need to do an extra database fetch and we can simply return it, wrapped in a list\r\n        if (processDefinitionEntity != null) {\r\n            return Collections.singletonList(processDefinitionEntity);\r\n        }\r\n\r\n        // Validation of input parameters\r\n        if (processDefinitionId == null && processDefinitionKey == null) {\r\n            throw new FlowableIllegalArgumentException(\"Process definition id or key cannot be null\");\r\n        }\r\n\r\n        List<ProcessDefinitionEntity> processDefinitionEntities = new ArrayList<>();\r\n        ProcessDefinitionEntityManager processDefinitionManager = CommandContextUtil.getProcessDefinitionEntityManager(commandContext);\r\n\r\n        if (processDefinitionId != null) {\r\n\r\n            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findById(processDefinitionId);\r\n            if (processDefinitionEntity == null) {\r\n                throw new FlowableObjectNotFoundException(\"Cannot find process definition for id '\" + processDefinitionId + \"'\", ProcessDefinition.class);\r\n            }\r\n            processDefinitionEntities.add(processDefinitionEntity);\r\n\r\n        } else {\r\n\r\n            ProcessDefinitionQueryImpl query = new ProcessDefinitionQueryImpl(commandContext).processDefinitionKey(processDefinitionKey);\r\n\r\n            if (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {\r\n                query.processDefinitionWithoutTenantId();\r\n            } else {\r\n                query.processDefinitionTenantId(tenantId);\r\n            }\r\n\r\n            List<ProcessDefinition> processDefinitions = query.list();\r\n            if (processDefinitions.isEmpty()) {\r\n                throw new FlowableException(\"Cannot find process definition for key '\" + processDefinitionKey + \"' and tenant '\" + tenantId + \"'\");\r\n            }\r\n\r","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java#L105-L141","documentation":"When a processDefinitionId is provided to findProcessDefinition, the command loads it via the entity manager; if no row matches, this FlowableObjectNotFoundException is thrown. The id must reference an existing, deployed process definition.","triggerScenarios":"Suspending/activating a process definition by id where the id is stale, belongs to another database, or was deleted.","commonSituations":"Ids persisted in app config that no longer exist after redeploy; environment mismatch (test id used in prod); definition removed by cleanup jobs.","solutions":["Resolve the id at runtime by key: createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId()","Validate the id with createProcessDefinitionQuery().processDefinitionId(id).singleResult() before executing the state change","Sync configuration across environments or store keys (not ids) in config"],"exampleFix":"// before\nmanagementService.activateProcessDefinitionById(\"orderProcess:2:77\").activate(); // deleted after redeploy\n// after\nString id = repositoryService.createProcessDefinitionQuery().processDefinitionKey(\"orderProcess\").latestVersion().singleResult().getId();\nmanagementService.activateProcessDefinitionById(id).activate();","handlingStrategy":"validation","validationCode":"ProcessDefinition pd = repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult();\nif (pd == null) throw new IllegalStateException(\"Cannot suspend: unknown definition id \" + id);","typeGuard":null,"tryCatchPattern":"try {\n    managementService.suspendProcessDefinitionById(id).suspend();\n} catch (FlowableObjectNotFoundException e) {\n    // id stale: re-resolve by key and retry\n}","preventionTips":["Resolve ids dynamically by key + latestVersion","Re-sync ids after every redeploy or definition cleanup","Never reuse ids captured from logs of other environments"],"tags":["flowable","process-definition-id","not-found"],"backgroundTag":"record-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}