flowable/flowable-engine · error · FlowableObjectNotFoundException

Historic variable instance '' couldn't be found.

Error message

Historic variable instance '' couldn't be found.

What it means

Thrown by the CMMN REST API when querying a historic variable instance by its unique id: historyService.createHistoricVariableInstanceQuery().id(varInstanceId).singleResult() returned null, so no historic variable instance with that id exists. The resource rethrows it as FlowableObjectNotFoundException and the REST layer maps it to HTTP 404. It is a pure id-lookup miss on the ACT_HI_VARINST table.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/history/variable/HistoricVariableInstanceBaseResource.java:107

        }

        if (queryRequest.getVariables() != null) {
            addVariables(query, queryRequest.getVariables());
        }
        
        if (restApiInterceptor != null) {
            restApiInterceptor.accessHistoryVariableInfoWithQuery(query, queryRequest);
        }

        return paginateList(allRequestParams, queryRequest, query, "variableName", allowedSortProperties,
                restResponseFactory::createHistoricVariableInstanceResponseList);
    }
    
    public RestVariable getVariableFromRequest(boolean includeBinary, String varInstanceId) {
        HistoricVariableInstance varObject = historyService.createHistoricVariableInstanceQuery().id(varInstanceId).singleResult();

        if (varObject == null) {
            throw new FlowableObjectNotFoundException("Historic variable instance '" + varInstanceId + "' couldn't be found.", VariableInstanceEntity.class);
        } else {
            if (restApiInterceptor != null) {
                restApiInterceptor.accessHistoryVariableInfoById(varObject);
            }
            return restResponseFactory.createRestVariable(varObject.getVariableName(), varObject.getValue(), null, varInstanceId, CmmnRestResponseFactory.VARIABLE_HISTORY_VARINSTANCE, includeBinary);
        }
    }

    protected void addVariables(HistoricVariableInstanceQuery variableInstanceQuery, List<QueryVariable> variables) {
        for (QueryVariable variable : variables) {
            if (variable.getVariableOperation() == null) {
                throw new FlowableIllegalArgumentException("Variable operation is missing for variable: " + variable.getName());
            }
            if (variable.getValue() == null) {
                throw new FlowableIllegalArgumentException("Variable value is missing for variable: " + variable.getName());
            }

            boolean nameLess = variable.getName() == null;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the varInstanceId by querying historyService.createHistoricVariableInstanceQuery().list() (or the REST list endpoint) and confirm the id exists.
2. Check that history level is at least 'audit' so variable instances are persisted to ACT_HI_VARINST.
3. Confirm you are pointing at the same database/engine that produced the id (CMMN vs BPMN, test vs prod).
4. If the id may be stale, re-resolve it by variableName/taskId instead of a hardcoded id.
5. Catch FlowableObjectNotFoundException on this endpoint when absence is an expected outcome.

Example fix

// before
RestVariable v = client.getHistoricVariableInstance(varInstanceId);

// after
try {
    RestVariable v = client.getHistoricVariableInstance(varInstanceId);
} catch (FlowableObjectNotFoundException e) {
    // fall back to lookup by name
    v = findByName(variableName);
}

HistoricVariableInstance v = historyService.createHistoricVariableInstanceQuery().id(varInstanceId).singleResult();
if (v == null) { /* resolve id before calling the REST endpoint */ }

try {
    RestVariable v = resource.getVariable(varInstanceId);
} catch (FlowableObjectNotFoundException e) {
    // HTTP 404: no historic variable instance with this id
}

When it happens

Trigger: GET /cmmn-history/historic-variable-instances/{varInstanceId} with an id that was never created, an id from a different engine/database, an id belonging to runtime variables only (ACT_RU_VARINST, never archived to history), or after history cleanup/level 0 history config removed the row.

Common situations: Clients cache variable instance ids across database resets or test runs, ids are copied from a process-engine (BPMN) deployment while querying the CMMN history API, or history level is set to none/activity so variable instances are never written to history.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Could not find a case instance with id '${caseInstanceId}'.
• Historic task instance '' variable value for couldn't be fo
• Could not find a process instance with id '" + processInstan
• Historic process instance '" + processInstanceId + "' could
• 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/9747ca1784f7fb7e. Report an issue: GitHub.