{"record":{"id":"fb036f6b41cb0d45","repo":"flowable/flowable-engine","slug":"cannot-find-process-definition-for-key-processde","errorCode":null,"errorMessage":"Cannot find process definition for key '{processDefinitionKey}' and tenant '{tenantId}'","messagePattern":"Cannot find process definition for key '(.+?)' and tenant '(.+?)'","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java","lineNumber":139,"sourceCode":"            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\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\r\n            if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {\r\n                continue;\r\n            }\r\n\r\n            TimerJobService timerJobService = CommandContextUtil.getTimerJobService(commandContext);\r","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessDefinitionStateCmd.java#L121-L157","documentation":"When resolving by processDefinitionKey, the command builds a ProcessDefinitionQuery (optionally tenant-scoped) and throws this FlowableException if the result list is empty. Note it does not auto-fallback to the default tenant: the tenant filter, if set, must match.","triggerScenarios":"managementService.suspendProcessDefinition().processDefinitionKey(...)[.processDefinitionTenantId(...)] where no latest definition exists for that key/tenant combination.","commonSituations":"Suspending by key before the first deployment; tenant filter not matching deployment tenant; key renamed in the BPMN model after an upgrade.","solutions":["Deploy the definition with that key, with the matching tenantId","Drop or correct processDefinitionTenantId so the query matches the deployment","Confirm the key with createProcessDefinitionQuery().processDefinitionKey(key).list()","Use byId resolution with the id fetched dynamically if key lookup keeps failing"],"exampleFix":"// before\nmanagementService.suspendProcessDefinition().processDefinitionKey(\"billing\").processDefinitionTenantId(\"acme\").suspend(); // deployed as default tenant\n// after\nmanagementService.suspendProcessDefinition().processDefinitionKey(\"billing\").suspend();","handlingStrategy":"validation","validationCode":"List<ProcessDefinition> defs = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(key)\n    .processDefinitionTenantId(tenantId, true).list();\nif (defs.isEmpty()) throw new IllegalStateException(\"No definition for key=\" + key + \" tenant=\" + tenantId);","typeGuard":null,"tryCatchPattern":"try {\n    managementService.suspendProcessDefinition().processDefinitionKey(key)\n        .processDefinitionTenantId(tenantId).suspend();\n} catch (FlowableException e) {\n    if (e.getMessage().startsWith(\"Cannot find process definition\")) {\n        // deploy or drop the tenant filter, then retry\n    }\n}","preventionTips":["Deploy before scheduling suspend/activate jobs by key","Match deployment tenantId with the tenant filter used in commands","Verify key+tenant with a query before executing state changes"],"tags":["flowable","suspend","process-definition","not-found","tenant"],"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"}