{"record":{"id":"02367a36fd980490","repo":"stanfordnlp/CoreNLP","slug":"mapdependencies-headfinder-failed","errorCode":null,"errorMessage":"mapDependencies: HeadFinder failed!","messagePattern":"mapDependencies: HeadFinder failed!","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/edu/stanford/nlp/trees/Tree.java","lineNumber":1387,"sourceCode":"   *           {@code CoreLabel}s, which each contain a tag(), word(),\n   *           and value(), the last two of which are identical).\n   */\n  public Set<Dependency<Label, Label, Object>> mapDependencies(Predicate<Dependency<Label, Label, Object>> f, HeadFinder hf) {\n    if (hf == null) {\n      throw new IllegalArgumentException(\"mapDependencies: need HeadFinder\");\n    }\n    Set<Dependency<Label, Label, Object>> deps = Generics.newHashSet();\n    for (Tree node : this) {\n      if (node.isLeaf() || node.children().length < 2) {\n        continue;\n      }\n      // Label l = node.label();\n      // log.info(\"doing kids of label: \" + l);\n      //Tree hwt = node.headPreTerminal(hf);\n      Tree hwt = node.headTerminal(hf);\n      // log.info(\"have hf, found head preterm: \" + hwt);\n      if (hwt == null) {\n        throw new IllegalStateException(\"mapDependencies: HeadFinder failed!\");\n      }\n\n      for (Tree child : node.children()) {\n        // Label dl = child.label();\n        // Tree dwt = child.headPreTerminal(hf);\n        Tree dwt = child.headTerminal(hf);\n        if (dwt == null) {\n          throw new IllegalStateException(\"mapDependencies: HeadFinder failed!\");\n        }\n        //log.info(\"kid is \" + dl);\n         //log.info(\"transformed to \" + dml.toString(\"value{map}\"));\n        if (dwt != hwt) {\n          Dependency<Label, Label, Object> p = new UnnamedDependency(hwt.label(), dwt.label());\n          if (f.test(p)) {\n            deps.add(p);\n          }\n        }\n      }","sourceCodeStart":1369,"sourceCodeEnd":1405,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/trees/Tree.java#L1369-L1405","documentation":"Inside mapDependencies, the head terminal of a multi-child node is computed via headTerminal(hf); if that returns null the dependency mapping cannot proceed. This is an IllegalStateException because by this point a valid HeadFinder was supplied, so the failure indicates the head finder could not resolve a head terminal for some node.","triggerScenarios":"headTerminal(hf) returns null for a node during mapDependencies — typically because determineHead returned null (no matching rule) or the node's head chain never reaches a terminal (malformed tree, node without leaf descendants).","commonSituations":"Trees with unlabelled or non-standard nodes; custom HeadFinders lacking default rules; running dependency conversion on truncated or hand-built trees that lack preterminal/leaf structure.","solutions":["Verify the tree is well-formed (every non-terminal has leaves beneath it) with tree.pennPrint()","Use a HeadFinder with a fallback rule such as CollinsHeadFinder or UniversalSemanticHeadFinder","Extend a custom HeadFinder to return a non-null head for every label it encounters"],"exampleFix":"// before\nTree hwt = node.headTerminal(myMinimalHeadFinder); // null for unknown labels\n// after\nHeadFinder hf = new CollinsHeadFinder();\nTree hwt = node.headTerminal(hf);","handlingStrategy":"try-catch","validationCode":"for (Tree n : tree) { if (!n.isLeaf() && n.children().length >= 2 && n.headTerminal(hf) == null) throw new IllegalStateException(\"no head terminal for \" + n); }","typeGuard":"boolean hasHeadTerminal(Tree t, HeadFinder hf) { return t.isLeaf() || t.headTerminal(hf) != null; }","tryCatchPattern":"try { deps = tree.mapDependencies(f, hf); } catch (IllegalStateException e) { log.error(\"HeadFinder failed on tree: {}\", tree.pennPrint()); }","preventionTips":["Sanity-check trees with pennPrint() before dependency conversion","Use head finders with fallback rules","Reject malformed trees early in your pipeline"],"tags":["nlp","dependencies","headfinder","invariant-violation"],"backgroundTag":"internal-invariant-violation","analyzedSha":"1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a","analyzedAt":"2026-09-10T02:24:07.274Z","contentChangedAt":"2026-09-10T02:24:07.274Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}