stanfordnlp/CoreNLP · error · IllegalArgumentException

Expected CoreLabels in the trees

Error message

Expected CoreLabels in the trees

What it means

percolateHeadAnnotations(HeadFinder) stores a HeadWordLabelAnnotation on each node pointing to the head word's CoreLabel; this requires every node label to be a CoreLabel. When the node's label is not a CoreLabel it throws IllegalArgumentException, as documented in its javadoc.

Solutions

1. Load/build the trees with CoreLabel labels (CoreLabel-based TreeFactory or reader option) before percolating annotations
2. Recursively convert all node labels to CoreLabels (copying value and, if needed, word/tag), then call percolateHeadAnnotations
3. Verify with a pre-check that every label() instanceof CoreLabel before invoking

Example fix

// before
tree.percolateHeadAnnotations(hf); // StringLabel tree -> throws
// after
TreeFactory tf = new TreeFactory(CoreLabel.factory());
Tree coreTree = rebuildWithCoreLabels(tree, tf);
coreTree.percolateHeadAnnotations(hf);

if (!(tree.label() instanceof CoreLabel)) throw new IllegalStateException("tree labels must be CoreLabels for percolateHeadAnnotations");

boolean allCoreLabels(Tree t) { return t.subTrees().stream().allMatch(n -> n.label() instanceof CoreLabel); }

try { tree.percolateHeadAnnotations(hf); } catch (IllegalArgumentException e) { tree = relabelWithCoreLabels(tree); tree.percolateHeadAnnotations(hf); }

When it happens

Trigger: Calling percolateHeadAnnotations(hf) on trees whose labels are not CoreLabel (StringLabel/WordTag trees), typically on the root — the check runs before recursion.

Common situations: Semantic/parsing pipelines needing head-word features (e.g. for ancestor/head-word models) fed with trees loaded via default readers using simple labels; mixing tree sources from different parsers.

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

• Expected leaves to be CoreLabels
• Expected CoreLabel's to have text
• Expected CoreLabel's to have after() text
• CORE: CoreLabel.initFromStrings: Can't handle
• CORE: CoreLabel.initFromStrings: Bad type for…

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

Appendix: source

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

    } else {
      Tree head = hf.determineHead(this);
      if (head != null) {
        return head.headPreTerminal(hf);
      }
      log.info("Head preterminal is null: " + this);
      return null;
    }
  }

  /**
   * Finds the head words of each tree and assigns
   * HeadWordLabelAnnotation on each node pointing to the correct
   * CoreLabel.  This relies on the nodes being CoreLabels, so it
   * throws an IllegalArgumentException if this is ever not true.
   */
  public void percolateHeadAnnotations(HeadFinder hf) {
    if (!(label() instanceof CoreLabel)) {
      throw new IllegalArgumentException("Expected CoreLabels in the trees");
    }
    CoreLabel nodeLabel = (CoreLabel) label();

    if (isLeaf()) {
      return;
    }

    if (isPreTerminal()) {
      nodeLabel.set(TreeCoreAnnotations.HeadWordLabelAnnotation.class, (CoreLabel) children()[0].label());
      nodeLabel.set(TreeCoreAnnotations.HeadTagLabelAnnotation.class, nodeLabel);
      return;
    }

    for (Tree kid : children()) {
      kid.percolateHeadAnnotations(hf);
    }

    final Tree head = hf.determineHead(this);

View on GitHub (pinned to 1b7edd19c4)