{"record":{"id":"cf393f5382455cbd","repo":"flowable/flowable-engine","slug":"could-not-find-a-process-instance-with-id-pro","errorCode":null,"errorMessage":"Could not find a process instance with id '\" + processInstanceId + \"'.","messagePattern":"Could not find a process instance with id '\" \\+ processInstanceId \\+ \"'\\.","errorType":"exception","errorClass":"FlowableObjectNotFoundException","httpStatus":404,"severity":"error","filePath":"modules/flowable-rest/src/main/java/org/flowable/rest/service/api/history/HistoricProcessInstanceBaseResource.java","lineNumber":304,"sourceCode":"        }\n        \n        return responseList;\n    }\n    \n    protected HistoricProcessInstance getHistoricProcessInstanceFromRequest(String processInstanceId) {\n        HistoricProcessInstance processInstance = getHistoricProcessInstanceFromRequestWithoutAccessCheck(processInstanceId);\n\n        if (restApiInterceptor != null) {\n            restApiInterceptor.accessHistoryProcessInfoById(processInstance);\n        }\n        \n        return processInstance;\n    }\n\n    protected HistoricProcessInstance getHistoricProcessInstanceFromRequestWithoutAccessCheck(String processInstanceId) {\n        HistoricProcessInstance processInstance = historyService.createHistoricProcessInstanceQuery().processInstanceId(processInstanceId).singleResult();\n        if (processInstance == null) {\n            throw new FlowableObjectNotFoundException(\"Could not find a process instance with id '\" + processInstanceId + \"'.\", HistoricProcessInstance.class);\n        }\n\n        return processInstance;\n    }\n\n    protected void addVariables(HistoricProcessInstanceQuery processInstanceQuery, List<QueryVariable> variables) {\n        for (QueryVariable variable : variables) {\n            if (variable.getVariableOperation() == null) {\n                throw new FlowableIllegalArgumentException(\"Variable operation is missing for variable: \" + variable.getName());\n            }\n            if (variable.getVariableOperation() != QueryVariableOperation.EXISTS && variable.getVariableOperation() != QueryVariableOperation.NOT_EXISTS) {\n                if (variable.getValue() == null) {\n                    throw new FlowableIllegalArgumentException(\"Variable value is missing for variable: \" + variable.getName());\n                }\n            }\n\n            boolean nameLess = variable.getName() == null;\n","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-rest/src/main/java/org/flowable/rest/service/api/history/HistoricProcessInstanceBaseResource.java#L286-L322","documentation":"A helper on HistoricProcessInstanceBaseResource queries historyService.createHistoricProcessInstanceQuery().processInstanceId(id).singleResult(); when the result is null it throws FlowableObjectNotFoundException. It means no historic process instance with that id exists in the history tables.","triggerScenarios":"GET /history/historic-process-instances/{processInstanceId} (and related sub-resources) with an id that never ran or whose history was purged.","commonSituations":"History level set to 'none' or 'audit' pruning instances; cleanup jobs deleting old history; using a runtime-only id before any history row exists or after engine migration.","solutions":["Confirm the processInstanceId by listing /history/historic-process-instances first","Check the engine's history level is high enough (audit/full) to record the instance","Catch FlowableObjectNotFoundException (HTTP 404) and handle 'no history' explicitly","Verify history cleanup configuration is not deleting the instance you need"],"exampleFix":"// before\ncurl /flowable-rest/history/historic-process-instances/wrong-id\n\n// after\n// find the correct id first\ncurl \"/flowable-rest/history/historic-process-instances?processDefinitionKey=myProcess\"\n// then\ncurl /flowable-rest/history/historic-process-instances/<correctId>","handlingStrategy":"validation","validationCode":"const list = await fetch(`${BASE}/history/historic-process-instances?processInstanceId=${id}`).then(r => r.json());\nif (!list.data || list.data.length === 0) throw new Error(`No history for process instance ${id}`);","typeGuard":"function isValidProcessInstanceId(id) { return typeof id === 'string' && id.length > 0; }","tryCatchPattern":"try { return await getHistoricProcessInstance(id); } catch (e) { if (e.status === 404) return null; throw e; }","preventionTips":["Confirm ids via list/search endpoints before direct lookups","Account for history cleanup jobs and history level settings","Cache runtime ids separately from historic ids"],"tags":["rest-api","flowable","history","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-14T05:17:10.506Z"}