{"record":{"id":"bf4558409361df27","repo":"flowable/flowable-engine","slug":"process-definition-with-key-processdefinitionke","errorCode":null,"errorMessage":"Process definition with key '${processDefinitionKey}' and tenantId '${tenantId}' was not found","messagePattern":"Process definition with key '(.+?)' and tenantId '(.+?)' was not found","errorType":"exception","errorClass":"FlowableObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/ProcessInstanceHelper.java","lineNumber":429,"sourceCode":"            if (parentDeploymentId != null) {\n                processDefinition = processDefinitionEntityManager\n                        .findProcessDefinitionByParentDeploymentAndKey(parentDeploymentId, processDefinitionKey);\n            }\n            if (processDefinition == null) {\n                processDefinition = processDefinitionEntityManager\n                        .findLatestProcessDefinitionByKey(processDefinitionKey);\n            }\n        }\n\n        if (processDefinition == null) {\n            if (tenantId == null || ProcessEngineConfiguration.NO_TENANT_ID.equals(tenantId)) {\n                throw new FlowableObjectNotFoundException(\n                        \"No process definition found for key '\" + processDefinitionKey + \"'\", ProcessDefinition.class);\n            } else if (fallbackToDefaultTenant) {\n                throw new FlowableObjectNotFoundException(\n                        \"No process definition found for key '\" + processDefinitionKey + \"'. Fallback to default tenant was also applied.\", ProcessDefinition.class);\n            } else {\n                throw new FlowableObjectNotFoundException(\n                        \"Process definition with key '\" + processDefinitionKey + \"' and tenantId '\" + tenantId + \"' was not found\", ProcessDefinition.class);\n            }\n        }\n\n        return processDefinition;\n    }\n\n    public void callCaseInstanceStateChangeCallbacks(CommandContext commandContext, ProcessInstance processInstance, String oldState, String newState) {\n        if (processInstance.getCallbackId() != null && processInstance.getCallbackType() != null) {\n            Map<String, List<RuntimeInstanceStateChangeCallback>> caseInstanceCallbacks = CommandContextUtil\n                    .getProcessEngineConfiguration(commandContext).getProcessInstanceStateChangedCallbacks();\n\n            if (caseInstanceCallbacks != null && caseInstanceCallbacks.containsKey(processInstance.getCallbackType())) {\n                for (RuntimeInstanceStateChangeCallback caseInstanceCallback : caseInstanceCallbacks.get(processInstance.getCallbackType())) {\n\n                    caseInstanceCallback.stateChanged(new CallbackData(processInstance.getCallbackId(), \n                        processInstance.getCallbackType(), processInstance.getId(), oldState, newState));\n","sourceCodeStart":411,"sourceCodeEnd":447,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/ProcessInstanceHelper.java#L411-L447","documentation":"Thrown by resolveProcessDefinition when a specific tenantId was supplied and no process definition exists with that key AND tenantId. Unlike the fallback case, no default-tenant fallback was requested or it was disabled, so the engine reports the exact key+tenant combination that was not found.","triggerScenarios":"startProcessInstanceByKey(key, tenantId, ...) variants (or resolveProcessDefinition called with fallbackToDefaultTenant=false) when the tenant never had this process deployed, including cases where the definition exists only under another tenant or the empty tenant.","commonSituations":"Wrong tenant id passed by configuration/env-var; process deployed with no tenant while the caller passes one; tenant ids case-mismatched; starting from an event/message path where the tenant was taken from a different source (e.g. user context) than the deployment.","solutions":["Confirm the exact tenantId used at deployment time and pass that same value to the start call.","Deploy the definition for the tenant if missing: createDeployment().tenantId(tenantId).addClasspathResource(...).deploy().","List where the key exists: repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).list() and read each definition's tenantId.","Enable fallbackToDefaultTenant if falling back to the default tenant is acceptable in your setup."],"exampleFix":"// before\nruntimeService.startProcessInstanceByKey(\"order\", \"ACME\", vars); // deployed as \"acme\"\n// after\nruntimeService.startProcessInstanceByKey(\"order\", \"acme\", vars); // match deployment tenantId exactly","handlingStrategy":"validation","validationCode":"ProcessDefinition def = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(key).processDefinitionTenantId(tenantId).latestVersion().singleResult();\nif (def == null) {\n    throw new IllegalStateException(\"No definition key='\" + key + \"' tenantId='\" + tenantId + \"' — deploy it first\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return runtimeService.startProcessInstanceByKey(key, tenantId, vars);\n} catch (FlowableObjectNotFoundException e) {\n    if (e.getMessage().contains(\"tenantId '\" + tenantId + \"' was not found\")) {\n        repositoryService.createDeployment().addClasspathResource(\"processes/\" + key + \".bpmn20.xml\").tenantId(tenantId).deploy();\n        return runtimeService.startProcessInstanceByKey(key, tenantId, vars);\n    }\n    throw e;\n}","preventionTips":["Read tenantId from the same source used at deployment time","Match tenant id casing exactly (ids are case-sensitive)","Script tenant deployments so every environment has all tenants","Log the resolved tenantId when starting instances for easier diagnosis"],"tags":["bpmn","tenant","not-found","flowable"],"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"}