flowable/flowable-engine · error · FlowableIllegalArgumentException
Could not find plan item instance for plan item with…
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.
Solutions
- Check ACT_CMMN_RU_PLAN_ITEM_INST for the expected planItemDefinitionId in that case instance.
- Align the case model plan item ids with the ones existing at suspension time; avoid renaming plan item ids of running cases.
- Use the latest case definition consistently and migrate/restart affected case instances.
- 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" .../>
Defensive patterns
Strategy: validation
Validate before calling
// java
PlanItemInstance pii = cmmnRuntimeService.createPlanItemInstanceQuery()
.caseInstanceId(caseInstanceId)
.planItemDefinitionId(planItemDefinitionId).singleResult();
if (pii == null) throw new IllegalStateException("Missing plan item instance: " + planItemDefinitionId); Try / catch
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
}
} Prevention
- Keep plan item ids stable across case model versions.
- Suspend/resume cases only after the plan model is fully initialized.
- Audit runtime plan item instances before reactivation.
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
- A dynamically created plan item can only be injected into a…
- Can only complete a stage plan item instance that is marked…
- Can only complete plan item instances of type stage. Type…
- Can only disable a plan item instance which is in state…
AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11).
Data as JSON: /api/errors/6d1d11d0ffb37300.
Report an issue: GitHub.
Appendix: 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)