stanfordnlp/CoreNLP · error · IllegalStateException

mapDependencies: HeadFinder failed!

Error message

mapDependencies: HeadFinder failed!

What it means

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.

Solutions

  1. Verify the tree is well-formed (every non-terminal has leaves beneath it) with tree.pennPrint()
  2. Use a HeadFinder with a fallback rule such as CollinsHeadFinder or UniversalSemanticHeadFinder
  3. Extend a custom HeadFinder to return a non-null head for every label it encounters

Example fix

// before
Tree hwt = node.headTerminal(myMinimalHeadFinder); // null for unknown labels
// after
HeadFinder hf = new CollinsHeadFinder();
Tree hwt = node.headTerminal(hf);
Defensive patterns

Strategy: try-catch

Validate before calling

for (Tree n : tree) { if (!n.isLeaf() && n.children().length >= 2 && n.headTerminal(hf) == null) throw new IllegalStateException("no head terminal for " + n); }

Type guard

boolean hasHeadTerminal(Tree t, HeadFinder hf) { return t.isLeaf() || t.headTerminal(hf) != null; }

Try / catch

try { deps = tree.mapDependencies(f, hf); } catch (IllegalStateException e) { log.error("HeadFinder failed on tree: {}", tree.pennPrint()); }

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of stanfordnlp/CoreNLP@1b7edd19c4 (2026-09-10). Data as JSON: /api/errors/02367a36fd980490. Report an issue: GitHub.

Appendix: source

Thrown at src/edu/stanford/nlp/trees/Tree.java:1387

   *           {@code CoreLabel}s, which each contain a tag(), word(),
   *           and value(), the last two of which are identical).
   */
  public Set<Dependency<Label, Label, Object>> mapDependencies(Predicate<Dependency<Label, Label, Object>> f, HeadFinder hf) {
    if (hf == null) {
      throw new IllegalArgumentException("mapDependencies: need HeadFinder");
    }
    Set<Dependency<Label, Label, Object>> deps = Generics.newHashSet();
    for (Tree node : this) {
      if (node.isLeaf() || node.children().length < 2) {
        continue;
      }
      // Label l = node.label();
      // log.info("doing kids of label: " + l);
      //Tree hwt = node.headPreTerminal(hf);
      Tree hwt = node.headTerminal(hf);
      // log.info("have hf, found head preterm: " + hwt);
      if (hwt == null) {
        throw new IllegalStateException("mapDependencies: HeadFinder failed!");
      }

      for (Tree child : node.children()) {
        // Label dl = child.label();
        // Tree dwt = child.headPreTerminal(hf);
        Tree dwt = child.headTerminal(hf);
        if (dwt == null) {
          throw new IllegalStateException("mapDependencies: HeadFinder failed!");
        }
        //log.info("kid is " + dl);
         //log.info("transformed to " + dml.toString("value{map}"));
        if (dwt != hwt) {
          Dependency<Label, Label, Object> p = new UnnamedDependency(hwt.label(), dwt.label());
          if (f.test(p)) {
            deps.add(p);
          }
        }
      }

View on GitHub (pinned to 1b7edd19c4)