{"record":{"id":"f075cc6463239143","repo":"flowable/flowable-engine","slug":"cannot-start-process-instance-process-model-nam","errorCode":null,"errorMessage":"Cannot start process instance. Process model ${name} (id = ${id}) could not be found","messagePattern":"Cannot start process instance\\. Process model (.+?) \\(id = (.+?)\\) could not be found","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"critical","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/ProcessInstanceHelper.java","lineNumber":94,"sourceCode":"            String callbackId, String callbackType, String referenceId, String referenceType, String ownerId, String assigneeId,\n            String stageInstanceId, boolean startProcessInstance) {\n\n        CommandContext commandContext = Context.getCommandContext();\n        if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {\n            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();\n            return compatibilityHandler.startProcessInstance(processDefinition.getKey(), processDefinition.getId(),\n                    variables, transientVariables, businessKey, processDefinition.getTenantId(), processInstanceName);\n        }\n\n        // Do not start process a process instance if the process definition is suspended\n        if (ProcessDefinitionUtil.isProcessDefinitionSuspended(processDefinition.getId())) {\n            throw new FlowableException(\"Cannot start process instance. Process definition \" + processDefinition.getName() + \" (id = \" + processDefinition.getId() + \") is suspended\");\n        }\n\n        // Get model from cache\n        Process process = ProcessDefinitionUtil.getProcess(processDefinition.getId());\n        if (process == null) {\n            throw new FlowableException(\"Cannot start process instance. Process model \" + processDefinition.getName() + \" (id = \" + processDefinition.getId() + \") could not be found\");\n        }\n        \n        FlowElement initialFlowElement = null;\n        if (StringUtils.isNotEmpty(startEventId)) {\n            FlowElement startEventFlowElement = process.getFlowElement(startEventId);\n            if (startEventFlowElement == null) {\n                throw new FlowableException(\"No start element found with id \" + startEventId + \" for process definition \" + processDefinition.getId());\n            }\n            \n            if (!(startEventFlowElement instanceof StartEvent)) {\n                throw new FlowableException(\"Provide start event id is not a start event \" + startEventId + \" for process definition \" + processDefinition.getId());\n            }\n            \n            initialFlowElement = startEventFlowElement;\n            \n        } else {\n            initialFlowElement = process.getInitialFlowElement();\n        }","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/util/ProcessInstanceHelper.java#L76-L112","documentation":"Flowable throws this when the in-memory BPMN process model for a resolved ProcessDefinition cannot be loaded from the deployment cache during process instance creation. ProcessDefinitionUtil.getProcess() returned null even though the definition entity exists, meaning the parsed model is unavailable. The engine refuses to continue because it needs the FlowElements to start execution.","triggerScenarios":"Calling RuntimeService.startProcessInstanceByKey/ById (or any variant routed through ProcessInstanceHelper.createProcessInstance) when ProcessDefinitionUtil.getProcess(processDefinition.getId()) returns null — i.e. the definition exists in ACT_RE_PROCDEF but its parsed BPMN model is absent from the deployment/process definition cache.","commonSituations":"Corrupted or manually pruned deployment cache; definitions deployed by an older engine version with an incompatible cache entry; multi-node setups sharing a database but not the cache after partial cache eviction; custom cache implementations returning null on miss; database rows manually manipulated (definition kept but deployment resources deleted).","solutions":["Redeploy the BPMN process model so the definition and its parsed model are rebuilt and cached.","Restart the process engine (or clear the process definition/deployment cache) so the model is reloaded from ACT_GE_BYTEARRAY.","Verify the deployment resources still exist in ACT_GE_BYTEARRAY; if deleted, redeploy and start with the new definition.","Check custom ProcessEngineConfiguration.getDeploymentManager/ProcessDefinitionCacheLimit implementations for cache eviction bugs.","If on a cluster, ensure all nodes are upgraded to the same Flowable version and share a consistent cache."],"exampleFix":"// before\nProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey(\"order\").singleResult();\nruntimeService.startProcessInstanceById(def.getId()); // model may be missing from cache\n// after\nProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionKey(\"order\").latestVersion().singleResult();\nif (def == null) throw new IllegalStateException(\"Deploy the 'order' process first\");\nrepositoryService.createDeployment().addClasspathResource(\"processes/order.bpmn20.xml\").deploy(); // ensures model is deployed+cached\nruntimeService.startProcessInstanceById(def.getId());","handlingStrategy":"validation","validationCode":"ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionId(defId).singleResult();\nif (def == null) throw new IllegalStateException(\"Definition not deployed: \" + defId);\n// ensure model resolvable\nBpmnModel model = repositoryService.getBpmnModel(defId);\nif (model == null || model.getMainProcess() == null || model.getMainProcess().getFlowElements().isEmpty()) {\n    throw new IllegalStateException(\"Parsed model unavailable for \" + defId + \" — redeploy the BPMN resource\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.startProcessInstanceById(defId);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"could not be found\")) {\n        repositoryService.createDeployment().addClasspathResource(\"processes/order.bpmn20.xml\").deploy();\n        runtimeService.startProcessInstanceById(defId);\n    } else { throw e; }\n}","preventionTips":["Deploy BPMN resources through the engine API only; never delete ACT_GE_BYTEARRAY rows manually","Keep clustered nodes on the same Flowable version and cache settings","Smoke-test instance startup right after each deployment","Avoid custom cache implementations unless they reload models on miss"],"tags":["bpmn","process-definition","deployment-cache","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-18T11:17:12.947Z"}