{"record":{"id":"9ed3c87eef2ff784","repo":"flowable/flowable-engine","slug":"no-matching-plan-item-definition-found-for-referen","errorCode":null,"errorMessage":"No matching plan item definition found for reference ${planItem.getDefinitionRef()} of plan item ${planItem.getId()}","messagePattern":"No matching plan item definition found for reference (.+?) of plan item (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/CmmnXmlConverter.java","lineNumber":517,"sourceCode":"            for (PlanItemDefinition planItemDefinition : stage.getPlanItemDefinitions()) {\n                if (planItemDefinition instanceof PlanFragment) {\n                    processPlanFragment(cmmnModel, (PlanFragment) planItemDefinition);\n                }\n            }\n\n            if (!stage.getExitCriteria().isEmpty()) {\n                resolveExitCriteriaSentry(stage);\n            }\n        }\n    }\n\n    protected void processPlanItems(CmmnModel cmmnModel, PlanFragment planFragment) {\n        for (PlanItem planItem : planFragment.getPlanItems()) {\n            // Plan items are defined on the same level or in a higher parent stage, never in a child stage.\n            Stage parentStage = planItem.getParentStage();\n            PlanItemDefinition planItemDefinition = parentStage.findPlanItemDefinitionInStageOrUpwards(planItem.getDefinitionRef());\n            if (planItemDefinition == null) {\n                throw new FlowableException(\"No matching plan item definition found for reference \"\n                    + planItem.getDefinitionRef() + \" of plan item \" + planItem.getId());\n            }\n\n            planItem.setPlanItemDefinition(planItemDefinition);\n            procesPlanItem(cmmnModel, planItem, planItemDefinition);\n\n        }\n\n    }\n\n    protected void procesPlanItem(CmmnModel cmmnModel, PlanItem planItem, PlanItemDefinition planItemDefinition) {\n        if (!planItem.getEntryCriteria().isEmpty()) {\n            resolveEntryCriteria(planItem);\n        }\n\n        if (!planItem.getExitCriteria().isEmpty()) {\n            resolveExitCriteriaSentry(planItem);\n        }","sourceCodeStart":499,"sourceCodeEnd":535,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/CmmnXmlConverter.java#L499-L535","documentation":"While post-processing the converted model, each PlanItem's definitionRef must resolve to a PlanItemDefinition in its parent stage or an ancestor stage. If planItem.getParentStage().findPlanItemDefinitionInStageOrUpwards(definitionRef) returns null, this FlowableException is thrown: the plan item references a definition that does not exist at or above its level.","triggerScenarios":"Deploying CMMN XML where a <planItem definitionRef=\"...\"> points to a definitionRef id that is not declared (or is declared only in a child stage or sibling), typically after renaming/deleting the referenced task/stage/event listener definition.","commonSituations":"Hand-editing or tool-generated CMMN with dangling definitionRef attributes, refactoring case definitions without updating plan items, copy-pasting plan items between stages/levels where the definition lives elsewhere.","solutions":["Open the CMMN XML and make every planItem's definitionRef match the id of a planItemDefinition declared in the same or an ancestor stage","Re-link the plan item in the Flowable modeler instead of hand-editing ids","Validate the XML against the CMMN 1.1 XSD and run the conversion before deployment","Search the file for the failing definitionRef value and correct or remove the orphan plan item"],"exampleFix":"// before\n<planItem id=\"planTask1\" definitionRef=\"task1\"/> <!-- task1 deleted -->\n// after\n<planItem id=\"planTask1\" definitionRef=\"humanTask1\"/> <!-- matches existing definition id -->","handlingStrategy":"validation","validationCode":"// Before deployment, check every planItem definitionRef resolves in the same or ancestor stage\nMap<String, Element> defs = collectIdsByElementName(doc, \"planItemDefinition\"); // task/humanTask/case/sentry-def ids\nfor (Element planItem : doc.getElementsByTagName(\"planItem\")) {\n    String ref = planItem.getAttribute(\"definitionRef\");\n    if (!defs.containsKey(ref)) throw new DeploymentException(\"Unresolved definitionRef: \" + ref);\n}","typeGuard":null,"tryCatchPattern":"try {\n    repositoryService.createDeployment().addClasspathResource(\"case.cmmn.xml\").deploy();\n} catch (FlowableException e) {\n    if (e.getMessage().startsWith(\"No matching plan item definition found\"))\n        log.error(\"Broken definitionRef in case model: \" + e.getMessage());\n    throw e;\n}","preventionTips":["Never hand-edit definitionRef ids; rename consistently or use the modeler","Keep plan item and definition ids unique and stable across edits","Validate CMMN (XSD + dry-run deployment to a test engine) in CI"],"tags":["cmmn","xml","model-validation","broken-reference"],"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"}