{"record":{"id":"6bc0f7e4a4fa3801","repo":"flowable/flowable-engine","slug":"cannot-find-process-definition-for-key-processd","errorCode":null,"errorMessage":"Cannot find process definition for key '${processDefinitionKey}'","messagePattern":"Cannot find process definition for key '(.+?)'","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java","lineNumber":119,"sourceCode":"            ProcessDefinitionEntity processDefinitionEntity = processDefinitionManager.findProcessDefinitionById(processDefinitionId);\r\n            if (processDefinitionEntity == null) {\r\n                throw new ActivitiObjectNotFoundException(\"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 ActivitiException(\"Cannot find process definition for key '\" + processDefinitionKey + \"'\");\r\n            }\r\n\r\n            for (ProcessDefinition processDefinition : processDefinitions) {\r\n                processDefinitionEntities.add((ProcessDefinitionEntity) processDefinition);\r\n            }\r\n\r\n        }\r\n        return processDefinitionEntities;\r\n    }\r\n\r\n    protected void createTimerForDelayedExecution(CommandContext commandContext, List<ProcessDefinitionEntity> processDefinitions) {\r\n        for (ProcessDefinitionEntity processDefinition : processDefinitions) {\r\n            TimerJobEntity timer = new TimerJobEntity();\r\n            timer.setJobType(Job.JOB_TYPE_TIMER);\r\n            timer.setRevision(1);\r\n            timer.setProcessDefinitionId(processDefinition.getId());\r\n\r\n            // Inherit tenant identifier (if applicable)\r","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java#L101-L137","documentation":"Thrown by AbstractSetProcessDefinitionStateCmd.findProcessDefinition when a query for process definitions by the given key (and optional tenant) returns no rows. The command cannot change the state (suspension/activation) of a definition that does not exist, so it fails fast with an ActivitiException.","triggerScenarios":"Calling RuntimeService.activateProcessDefinitionByKey/suspendProcessDefinitionByKey (or by key and tenant id) with a processDefinitionKey that has no deployed definition, a typo in the key, or a tenantId that does not match the deployment's tenant.","commonSituations":"Deployed the process under a different key than the one referenced in code/config; multi-tenant setup where the definition is deployed to tenant A but queried with tenant B (or null vs explicit tenant mismatch); running against a fresh database where the deployment never happened.","solutions":["Verify the processDefinitionKey matches the <process id=\"...\"> in the BPMN XML of a deployed definition (query ACT_RE_PROCDEF or RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).list()).","If using tenant id, confirm the definition is deployed with that exact tenantId; use activateProcessDefinitionByKey(key).processDefinitionTenantId(...) consistently with the deployment.","Deploy the missing process definition first via RepositoryService.createDeployment().addClasspathResource(...).tenantId(...).deploy().","Fix typos/case in the key; keys are matched exactly."],"exampleFix":"// before\nruntimeService.suspendProcessDefinitionByKey(\"ordeProcess\");\n// after\nruntimeService.suspendProcessDefinitionByKey(\"orderProcess\"); // key matches deployed BPMN <process id=\"orderProcess\">","handlingStrategy":"validation","validationCode":"long count = repositoryService.createProcessDefinitionQuery().processDefinitionKey(key)\n    .latestVersion().count();\nif (count == 0) { throw new IllegalStateException(\"No deployed definition for key \" + key); }","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.suspendProcessDefinitionByKey(key);\n} catch (ActivitiException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Cannot find process definition for key\")) {\n        logger.warn(\"Definition {} not deployed\", key);\n    } else { throw e; }\n}","preventionTips":["Query ProcessDefinitionQuery by key before state changes","Keep deployment keys in shared constants/config, not string literals","In multi-tenant setups, always pair key with the deployment tenantId","Add an integration test that exercises suspend/activate against a real deployment"],"tags":["process-definition","not-found","workflow","activiti"],"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-14T11:17:12.474Z"}