flowable/flowable-engine · error · FlowableObjectNotFoundException

Historic case instance '${caseInstanceId}' variable value fo

Error message

Historic case instance '${caseInstanceId}' variable value for ${variableName} couldn't be found.

What it means

FlowableObjectNotFoundException thrown when a historic case instance variable (or its value) cannot be found by name for the given historic case instance. The query historyService.createHistoricVariableInstanceQuery() either returned no row or the stored value was null. The message embeds the caseInstanceId and variableName for diagnosis.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/history/caze/HistoricCaseInstanceVariableDataResource.java:100

            }
            return result;

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

    public RestVariable getVariableFromRequest(boolean includeBinary, String caseInstanceId, String variableName) {
        HistoricCaseInstance caseObject = getHistoricCaseInstanceFromRequest(caseInstanceId);

        HistoricVariableInstance variable = historyService.createHistoricVariableInstanceQuery()
                        .caseInstanceId(caseObject.getId())
                        .variableName(variableName)
                        .singleResult();

        if (variable == null || variable.getValue() == null) {
            throw new FlowableObjectNotFoundException("Historic case instance '" + caseInstanceId + "' variable value for " + variableName + " couldn't be found.", VariableInstanceEntity.class);
        } else {
            return restResponseFactory.createRestVariable(variableName, variable.getValue(), null, caseInstanceId, CmmnRestResponseFactory.VARIABLE_HISTORY_CASE, includeBinary);
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Verify the caseInstanceId exists: GET /cmmn-history/historic-case-instances/{caseInstanceId}.
List all historic variables via GET /cmmn-history/historic-case-instances/{caseInstanceId}/variables to confirm the exact name.
Catch FlowableObjectNotFoundException and return 404 to the client instead of letting it bubble as 500.
Check the engine's history level configuration includes variable history (historyLevel >= audit).
If the value was legitimately null, treat 'null value' as expected and handle it client-side.

Example fix

// before
RestVariable v = client.getHistoricCaseVariable(caseId, "orderTotal");
// after
try {
    RestVariable v = client.getHistoricCaseVariable(caseId, "orderTotal");
} catch (FlowableObjectNotFoundException e) {
    return ResponseEntity.notFound().build();
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check: GET /cmmn-history/historic-case-instances/{caseId}/variables
// and confirm the variableName exists and value != null

Try / catch

try {
    RestVariable v = getHistoricCaseVariable(caseId, name);
} catch (FlowableObjectNotFoundException e) {
    return ResponseEntity.notFound().build();
}

Prevention

List historic variables first instead of guessing names.
Remember null-valued variables are indistinguishable from missing ones here.
Ensure history level (audit/full) retains variable history.
Validate caseInstanceId before querying variables.

When it happens

Trigger: GET /cmmn-history/historic-case-instances/{caseInstanceId}/variables/{variableName} (via the variable endpoint calling getVariableFromRequest) with a variableName that has no matching historic variable instance, or whose value is null (e.g. the variable was set to null before case completion).

Common situations: Typo in the variable name; querying a variable that was only ever null; case history not retained (history level too low); wrong caseInstanceId (no such historic case); variable scoped to a child plan item rather than the case.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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