flowable/flowable-engine · error · FlowableObjectNotFoundException

Historic process instance '" + processInstanceId + "'…

Error message

Historic process instance '" + processInstanceId + "' variable value for " + variableName + " could not be found.

What it means

The historic process instance exists, but the requested variable name is not among its persisted process variables, so Flowable throws FlowableObjectNotFoundException for VariableInstanceEntity. Note the value==null check also fires if the historic variable value itself was stored as null.

Solutions

List available variables first: GET /history/historic-process-instances/{id}/variables and confirm the exact name
Correct the variableName spelling/casing in the client request
If the variable lives on a task, query the historic task instance variables endpoint instead
Raise history level to 'audit' (or 'full') so process variables are recorded in history

Example fix

// before
RestVariable v = getVariableFromRequest(true, procInstId, "OrderAmount");
// after
Map<String, Object> vars = historyService.createHistoricProcessInstanceQuery()
    .processInstanceId(procInstId).includeProcessVariables().singleResult().getProcessVariables();
if (vars.containsKey("orderAmount")) {
    RestVariable v = getVariableFromRequest(true, procInstId, "orderAmount");
}

Defensive patterns

Strategy: validation

Validate before calling

HistoricProcessInstance p = historyService.createHistoricProcessInstanceQuery()
    .processInstanceId(id).includeProcessVariables().singleResult();
if (p == null || !p.getProcessVariables().containsKey(variableName)) {
    throw new IllegalArgumentException("Variable not found: " + variableName);
}

Try / catch

try { return getHistoryVariable(id, name); }
catch (FlowableObjectNotFoundException e) { return Collections.emptyMap(); }

Prevention

List all historic variables before fetching one by name
Match variable name and casing exactly as set in the process
For task-scoped variables use the historic task variable endpoints

When it happens

Trigger: GET /history/historic-process-instances/{id}/variables/{variableName} where variableName was never set on the process (or via getVariableFromRequest with an unknown/wrong variable name).

Common situations: Variable renamed in a later process definition version; variable scoped to a task, not the process; misspelled variable name; history level 'activity' does not persist variable values so nothing is found.

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

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

Appendix: source

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

        }
    }

    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)