flowable/flowable-engine · error · FlowableIllegalArgumentException

Could not find plan item instance for plan item with definit

Error message

Could not find plan item instance for plan item with definition id {planItemDefinitionId}

What it means

searchPlanItemInstance scans the child plan item instances of a case for one whose planItemDefinitionId equals the requested id, and throws if none matches. It is used during case reactivation, both to find the reactivation listener and to reactivate dependent plan items.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/agenda/operation/ReactivateCaseInstanceOperation.java:127

            .caseDefinitionId(planItemInstance.getCaseDefinitionId())
            .caseInstanceId(planItemInstance.getCaseInstanceId())
            .stagePlanItemInstance(stagePlanItem)
            .tenantId(planItemInstance.getTenantId())
            .addToParent(true)
            .silentNameExpressionEvaluation(false)
            .create();

        CommandContextUtil.getAgenda(commandContext).planReactivatePlanItemInstanceOperation(reactivatedPlanItemInstance);
        return reactivatedPlanItemInstance;
    }

    protected PlanItemInstanceEntity searchPlanItemInstance(String planItemDefinitionId, List<PlanItemInstanceEntity> planItemInstances) {
        for (PlanItemInstanceEntity planItemInstance : planItemInstances) {
            if (planItemInstance.getPlanItemDefinitionId().equals(planItemDefinitionId)) {
                return planItemInstance;
            }
        }
        throw new FlowableIllegalArgumentException("Could not find plan item instance for plan item with definition id " + planItemDefinitionId);
    }

    @Override
    public String toString() {
        return "[Init Plan Model] initializing plan model for case instance " + caseInstanceEntity.getId();
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check ACT_CMMN_RU_PLAN_ITEM_INST for the expected planItemDefinitionId in that case instance.
2. Align the case model plan item ids with the ones existing at suspension time; avoid renaming plan item ids of running cases.
3. Use the latest case definition consistently and migrate/restart affected case instances.
4. Wrap reactivation in try-catch for FlowableIllegalArgumentException and fall back to manual data repair.

Example fix

// before: renamed planItem id 'approveTask' to 'approvalTask' in a running case
// after: keep ids stable
<planItem id="approveTask" name="Approve" .../>

// java
PlanItemInstance pii = cmmnRuntimeService.createPlanItemInstanceQuery()
    .caseInstanceId(caseInstanceId)
    .planItemDefinitionId(planItemDefinitionId).singleResult();
if (pii == null) throw new IllegalStateException("Missing plan item instance: " + planItemDefinitionId);

try {
    cmmnRuntimeService.resumeCaseInstance(caseInstanceId);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().startsWith("Could not find plan item instance")) {
        // inspect ACT_CMMN_RU_PLAN_ITEM_INST and repair
    }
}

When it happens

Trigger: Reactivating a case where the ReactivateEventListener id or a depending plan item's id referenced by the reactivation logic does not match any child plan item instance (never created, already removed, or definition id changed after redeployment).

Common situations: Case model refactoring renamed a plan item id; suspension happened before dependent plan items existed; database contains plan item instances from an older case definition version.

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

• incorrect plan item definition id passed
• There can only be one reactivation listener on a case model,
• Plan item instance for {eventSubscription} can not be found
• Could not find reactivation listener plan item instance in c
• Can only trigger a plan item that is in the ACTIVE state

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