What causes "Could not find a plan item instance" in flowable/flowable-engine?

Fetch a valid plan item instance id via the plan-item-instance query endpoints first

flowable/flowable-engine · error · FlowableObjectNotFoundException

Could not find a plan item instance

Error message

Could not find a plan item instance

What it means

The PlanItemInstance overload of getVariableFromRequest throws FlowableObjectNotFoundException when given a null planItemInstance, indicating the plan item instance could not be resolved before reading its variables.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/caze/BaseVariableResource.java:98

        return planItemInstance;
    }

    public RestVariable getVariableFromRequest(CaseInstance caseInstance, String variableName, boolean includeBinary) {

        if (caseInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a case instance", CaseInstance.class);
        }

        if (restApiInterceptor != null) {
            restApiInterceptor.accessCaseInstanceVariable(caseInstance, variableName);
        }

        return getVariableFromRequestWithoutAccessCheck(caseInstance.getId(), variableName, CmmnRestResponseFactory.VARIABLE_CASE, includeBinary);
    }

    public RestVariable getVariableFromRequest(PlanItemInstance planItemInstance, String variableName, boolean includeBinary) {
        if (planItemInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a plan item instance", CaseInstance.class);
        }

        if (restApiInterceptor != null) {
            restApiInterceptor.accessPlanItemInstanceVariable(planItemInstance, variableName);
        }
        return getVariableFromRequestWithoutAccessCheck(planItemInstance.getId(), variableName, CmmnRestResponseFactory.VARIABLE_PLAN_ITEM, includeBinary);
    }

    protected RestVariable getVariableFromRequestWithoutAccessCheck(String instanceId, String variableName, int variableType, boolean includeBinary) {
        Object value = null;

        if (variableType == CmmnRestResponseFactory.VARIABLE_PLAN_ITEM) {
            value = runtimeService.getLocalVariable(instanceId, variableName);
        } else if (variableType == CmmnRestResponseFactory.VARIABLE_CASE) {
            value = runtimeService.getVariable(instanceId, variableName);
        } else {
            throw new FlowableIllegalArgumentException("Unknown variable type " + variableType);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Fetch a valid plan item instance id via the plan-item-instance query endpoints first
Use case-level variable endpoints for completed plan items (history)
Validate the id before calling the variable endpoint

Example fix

// before
restVariable = getVariableFromRequest(null, variableName, false);
// after
PlanItemInstance pii = resolvePlanItemInstance(id); // must be non-null
restVariable = getVariableFromRequest(pii, variableName, false);

Defensive patterns

Strategy: try-catch

Validate before calling

const res = await fetch(`/cmmn-runtime/plan-item-instances/${planItemInstanceId}`);
if (!res.ok) throw new Error('Plan item instance not found: ' + planItemInstanceId);

Type guard

if (planItemInstance == null) { /* handle not-found upstream */ }

Try / catch

try { ... } catch (e) {
  if (e instanceof FlowableObjectNotFoundException) { /* re-resolve plan item or use history */ }
}

Prevention

Confirm plan item still exists at runtime before variable access
Use plan-item-instance query endpoints to validate ids
Handle completed plan items via history variable queries

When it happens

Trigger: Calling the plan-item variable REST endpoint where getPlanItemInstanceFromRequest returned null (unknown planItemInstanceId) and the null instance is then passed into getVariableFromRequest(PlanItemInstance, ...).

Common situations: Completed/terminated plan items no longer present in runtime data; wrong plan-item-instance id; ids from a different engine database.

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/59667694af3c8883. Report an issue: GitHub.