stanfordnlp/CoreNLP · error · IllegalArgumentException

Cannot process tree: <tree>

Error message

Cannot process tree:
<tree>

What it means

After building the tree graph, GrammaticalStructure calls root.percolateHeads(headFinder). If the HeadFinder cannot assign heads (it throws IllegalArgumentException because no head can be determined for some node, e.g. unknown category labels), the constructor rethrows with 'Cannot process tree:' plus the tree's string form and the original cause. It means the tree's structure or labels are incompatible with the supplied head finder.

Solutions

1. Inspect the wrapped IllegalArgumentException cause and the printed tree to find the node whose head could not be percolated
2. Use the HeadFinder matching the tree's annotation scheme (e.g. UniversalSemanticHeadFinder for universal trees)
3. Ensure the tree is fully bracketed with POS tags and a ROOT node (run through a TreeNormalizer/TreeBank processing first)
4. Fix missing or malformed category labels on the offending nodes

Example fix

// before
GrammaticalStructure gs = new EnglishGrammaticalStructure(tree, puncFilter, new ChineseHeadFinder(), ...);
// after
GrammaticalStructure gs = new EnglishGrammaticalStructure(tree, puncFilter, new UniversalSemanticHeadFinder(), ...);

// verify head finder compatibility before building
if (tree.value() == null || tree.value().isEmpty())
    throw new IllegalArgumentException("Tree lacks ROOT value");
for (Tree t : tree) if (t.isLeaf() && (t.value() == null || t.value().isEmpty()))
    throw new IllegalArgumentException("Tree has unlabeled leaf");

try {
    GrammaticalStructure gs = new EnglishGrammaticalStructure(t, puncFilter, hf, null);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Cannot process tree:")) {
        // inspect e.getCause() and the printed tree; retry with correct HeadFinder
    } else throw e;
}

When it happens

Trigger: Constructing a GrammaticalStructure from a tree whose node values/categories the HeadFinder doesn't recognize (e.g. a UniversalDependencies-ish or treebank-mismatched tree); passing a HeadFinder for the wrong annotation scheme (e.g. Chinese head finder on an English tree); a tree with a node that has no children and no resolvable head.

Common situations: Feeding parser output from one grammar into a dependency converter tuned for another; manually built trees missing ROOT or POS structure; mixing UniversalSemanticHeadFinder with non-universal trees.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Shouldn't happen:
• unexpected match type
• Classes derived from AbstractCollinsHeadFinder must create a
• Unknown grammatical relation '
• Transformer did not change TreeGraphNode into another TreeGr

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

Appendix: source

Thrown at src/edu/stanford/nlp/trees/GrammaticalStructure.java:186

    if (transformer != null) {
      Tree transformed = transformer.transformTree(treeGraph);
      if (!(transformed instanceof TreeGraphNode)) {
        throw new RuntimeException("Transformer did not change TreeGraphNode into another TreeGraphNode: " + transformer);
      }
      this.root = (TreeGraphNode) transformed;
    } else {
      this.root = treeGraph;
    }
    //System.out.println(this.root.toPrettyString(2));
    indexNodes(this.root);
    // add head word and tag to phrase nodes
    if (hf == null) {
      throw new AssertionError("Cannot use null HeadFinder");
    }
    try {
      root.percolateHeads(hf);
    } catch (IllegalArgumentException e) {
      throw new IllegalArgumentException("Cannot process tree:\n" + t, e);
    }
    if (root.value() == null) {
      root.setValue("ROOT");  // todo: cdm: it doesn't seem like this line should be here
    }
    // add dependencies, using heads
    this.puncFilter = puncFilter;
    this.tagFilter = tagFilter;
    // NoPunctFilter puncDepFilter = new NoPunctFilter(puncFilter);
    NoPunctTypedDependencyFilter puncTypedDepFilter = new NoPunctTypedDependencyFilter(puncFilter, tagFilter);

    DirectedMultiGraph<TreeGraphNode, GrammaticalRelation> basicGraph = new DirectedMultiGraph<>();
    DirectedMultiGraph<TreeGraphNode, GrammaticalRelation> completeGraph = new DirectedMultiGraph<>();

    // analyze the root (and its descendants, recursively)
    if (relationsLock != null) {
      relationsLock.lock();
    }
    try {

View on GitHub (pinned to 1b7edd19c4)