flowable/flowable-engine · error · FlowableObjectNotFoundException

Could not find a plan item instance with id '${planItemInsta

Error message

Could not find a plan item instance with id '${planItemInstanceId}'.

What it means

getPlanItemInstanceFromRequest queries the runtime for a plan item instance by id; when no match is found it throws FlowableObjectNotFoundException. The supplied planItemInstanceId does not reference an existing plan item instance in the CMMN runtime.

Source

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

    @Autowired
    protected ObjectMapper objectMapper;

    
    @Autowired
    protected Environment env;
    
    protected boolean isSerializableVariableAllowed;

    @Override
    public void afterPropertiesSet() {
        isSerializableVariableAllowed = env.getProperty("rest.variables.allow.serializable", Boolean.class, true);
    }

    protected PlanItemInstance getPlanItemInstanceFromRequest(String planItemInstanceId) {
        PlanItemInstance planItemInstance = runtimeService.createPlanItemInstanceQuery().planItemInstanceId(planItemInstanceId).singleResult();
        if (planItemInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a plan item instance with id '" + planItemInstanceId + "'.");
        }

        if (restApiInterceptor != null) {
            restApiInterceptor.accessPlanItemInstanceInfoById(planItemInstance);
        }

        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);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Verify the planItemInstanceId exists via GET plan-item-instance queries first
Use the correct id type (plan item instance id, not case instance id or plan item definition id)
Check whether the plan item already completed — historical data lives in the history service, not runtime
Confirm you are pointed at the same database/tenant where the case is running

Example fix

// before
String id = caseInstance.getId(); // wrong id
// after
PlanItemInstance pii = runtimeService.createPlanItemInstanceQuery().planItemInstanceCaseInstanceId(caseInstance.getId()).singleResult();
String id = pii.getId();

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

try { ... } catch (e) {
  if (e instanceof FlowableObjectNotFoundException) {
    // fall back to history query for completed plan items
  }
}

Prevention

Resolve plan item ids via query endpoints before variable operations
Remember completed plan items leave the runtime (use history)
Don't confuse case instance ids with plan item instance ids

When it happens

Trigger: Calling plan-item variable endpoints (e.g. GET/PUT/DELETE on plan-item variable resources) with a planItemInstanceId path parameter that is nonexistent, already completed/terminated (moved out of runtime), or malformed.

Common situations: Using a case instance id instead of a plan item instance id; plan item completed so it no longer appears in plan item instance runtime data; stale ids saved from a previous session; wrong tenant/database.

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/8cfefbd4e3399d1c. Report an issue: GitHub.