{"record":{"id":"aab40e7abe0a84e2","repo":"flowable/flowable-engine","slug":"plan-item-could-not-be-found-for-planiteminstanc","errorCode":null,"errorMessage":"Plan item could not be found for ${planItemInstance}","messagePattern":"Plan item could not be found for (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/util/PlanItemInstanceContainerUtil.java","lineNumber":221,"sourceCode":"            for (PlanItemInstanceEntity item : planItemInstances) {\n                if (Objects.equals(planItemInstance.getStageInstanceId(), item.getStageInstanceId()) && COMPLETED.equals(item.getState())) {\n                    return true;\n                }\n            }\n        }\n        return false;\n    }\n\n    /**\n     * Checks the plan items parent completion mode to be equal to a given type and returns true if so.\n     *\n     * @param planItemInstance the plan item to check for a parent completion mode\n     * @param parentCompletionRuleType the parent completion type to check against\n     * @return true, if there is a parent completion mode set on the plan item equal to the given one\n     */\n    public static boolean isParentCompletionRuleForPlanItemEqualToType(PlanItemInstanceEntity planItemInstance, String parentCompletionRuleType) {\n        if (planItemInstance.getPlanItem() == null) {\n            throw new FlowableException(\"Plan item could not be found for \" + planItemInstance);\n        }\n        \n        if (planItemInstance.getPlanItem().getItemControl() != null && planItemInstance.getPlanItem().getItemControl().getParentCompletionRule() != null) {\n            ParentCompletionRule parentCompletionRule = planItemInstance.getPlanItem().getItemControl().getParentCompletionRule();\n            if (parentCompletionRuleType.equals(parentCompletionRule.getType())) {\n                return true;\n            }\n        }\n        return false;\n    }\n\n}\n","sourceCodeStart":203,"sourceCodeEnd":234,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/util/PlanItemInstanceContainerUtil.java#L203-L234","documentation":"PlanItemInstanceContainerUtil.isParentCompletionRuleForPlanItemEqualToType inspects the plan item's itemControl to compare its parentCompletionRule type. If the PlanItemInstanceEntity has no PlanItem reference (a degraded/inconsistent state — the runtime instance lost its link to its model element), it throws this FlowableException since the parent completion mode cannot be determined.","triggerScenarios":"Calling shouldPlanItemContainerComplete / shouldIgnorePlanItemForCompletion during case completion evaluation when a planItemInstance.getPlanItem() is null — e.g. after partial engine state, an inconsistent upgrade, or a plan item instance built without its definition attached.","commonSituations":"Custom code creating or migrating PlanItemInstanceEntity instances without setting the PlanItem definition; corrupted/incompletely deployed case definitions after a model change; recompletion of historic plan items.","solutions":["Ensure PlanItemInstanceEntity.setPlanItem(definition) is set wherever the entity is created or restored (including custom migration/import code)","Redeploy/refresh the case definition so runtime plan items resolve their model elements","Check for engine/version upgrade migration gaps and re-run any missing Flowable migration steps","If reachable for historic/stale instances, guard the completion logic to skip plan items whose definition is gone after investigating why"],"exampleFix":"// before\nboolean ignore = PlanItemInstanceContainerUtil.isParentCompletionRuleForPlanItemEqualToType(planItemInstance, ParentCompletionRule.IGNORE);\n// after\nif (planItemInstance.getPlanItem() == null) {\n    throw new IllegalStateException(\"PlanItem definition missing for \" + planItemInstance.getId() + \"; check deployment/migration\");\n}\nboolean ignore = PlanItemInstanceContainerUtil.isParentCompletionRuleForPlanItemEqualToType(planItemInstance, ParentCompletionRule.IGNORE);","handlingStrategy":"validation","validationCode":"if (planItemInstance.getPlanItem() == null) {\n    throw new IllegalStateException(\"PlanItemInstance \" + planItemInstance.getId() + \" has no PlanItem definition; deployment/migration issue\");\n}","typeGuard":"boolean hasPlanItemDefinition(PlanItemInstanceEntity pii) { return pii != null && pii.getPlanItem() != null; }","tryCatchPattern":"try { return isParentCompletionRuleForPlanItemEqualToType(pii, type); } catch (FlowableException e) { if (e.getMessage().startsWith(\"Plan item could not be found\")) { log.error(\"Missing plan item definition for {}\", pii.getId()); throw new IllegalStateException(\"Corrupt plan item state\", e); } throw e; }","preventionTips":["Always set the PlanItem definition when constructing/restoring plan item instances","Re-run engine migrations after Flowable upgrades","Redeploy case definitions when model elements go missing at runtime"],"tags":["cmmn","plan-item","internal-state","flowable"],"backgroundTag":"entity-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}