flowable/flowable-engine · error · FlowableObjectNotFoundException

Historic process instance '" + processInstanceId + "' could

Error message

Historic process instance '" + processInstanceId + "' could not be found.

What it means

Flowable's historic process instance REST resource throws FlowableObjectNotFoundException when a query by processInstanceId finds no historic process instance. The historyService query returned no row, so the requested historic instance (or its id) does not exist in the ACT_HI_PROCINST table. The exception carries HistoricProcessInstanceEntity.class as the resolved resource type.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/history/HistoricProcessInstanceVariableDataResource.java:96

                response.setContentType("application/x-java-serialized-object");

            } else {
                throw new FlowableObjectNotFoundException("The variable does not have a binary data stream.", null);
            }
            return result;

        } catch (IOException ioe) {
            // Re-throw IOException
            throw new FlowableException("Unexpected exception getting variable data", ioe);
        }
    }

    public RestVariable getVariableFromRequest(boolean includeBinary, String processInstanceId, String variableName) {

        HistoricProcessInstance processObject = historyService.createHistoricProcessInstanceQuery().processInstanceId(processInstanceId).includeProcessVariables().singleResult();

        if (processObject == null) {
            throw new FlowableObjectNotFoundException("Historic process instance '" + processInstanceId + "' could not be found.", HistoricProcessInstanceEntity.class);
        }
        
        if (restApiInterceptor != null) {
            restApiInterceptor.accessHistoryProcessInfoById(processObject);
        }

        Object value = processObject.getProcessVariables().get(variableName);

        if (value == null) {
            throw new FlowableObjectNotFoundException("Historic process instance '" + processInstanceId + "' variable value for " + variableName + " could not be found.", VariableInstanceEntity.class);
        } else {
            return restResponseFactory.createRestVariable(variableName, value, null, processInstanceId, RestResponseFactory.VARIABLE_HISTORY_PROCESS, includeBinary);
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the processInstanceId exists: query ACT_HI_PROCINST or call historyService.createHistoricProcessInstanceQuery().processInstanceId(id).singleResult() first
2. If the process is still running, use the runtime API (RuntimeService/ProcessInstanceQuery) instead of the history API
3. Check the engine's history level configuration; raise it (at least 'activity' or 'audit') so historic instances are recorded
4. Check whether history cleanup job removed the row and use a backup/copy if needed

Example fix

// before
HistoricProcessInstance p = historyService.createHistoricProcessInstanceQuery().processInstanceId(id).singleResult();
RestVariable v = getVariableFromRequest(true, id, name); // throws if p == null
// after
HistoricProcessInstance p = historyService.createHistoricProcessInstanceQuery().processInstanceId(id).singleResult();
if (p == null) {
    // handle missing history gracefully
    return fallbackResponse(id);
}
RestVariable v = getVariableFromRequest(true, id, name);

HistoricProcessInstance p = historyService.createHistoricProcessInstanceQuery()
    .processInstanceId(processInstanceId).singleResult();
if (p == null) { throw new IllegalArgumentException("Unknown historic instance: " + processInstanceId); }

try { RestVariable v = rest.get(...); }
catch (FlowableObjectNotFoundException e) {
    if (HistoricProcessInstanceEntity.class.equals(e.getObjectClass())) { /* handle missing history */ }
    else throw e;
}

When it happens

Trigger: Calling GET on the history process-instance variable endpoint (e.g. /history/historic-process-instances/{processInstanceId}/variables/{variableName}) via getVariableFromRequest with a processInstanceId that has no historic process instance row.

Common situations: Typo or wrong-case instance id; querying a still-running process (only completed/moved-to-history instances appear); history level configured too low (e.g. 'none'/'activity') so no instance rows are written; cleanup/job purged the history row; querying the wrong engine datasource.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Could not find a case instance with id '${caseInstanceId}'.
• Historic task instance '' variable value for couldn't be fo
• Historic variable instance '' couldn't be found.
• Could not find a process instance with id '" + processInstan
• Could not find a task instance with id '" + taskId + "'.

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/1b5660964cf97340. Report an issue: GitHub.