{"record":{"id":"10387929b5008d3d","repo":"stanfordnlp/CoreNLP","slug":"headfinder","errorCode":null,"errorMessage":"HeadFinder ","messagePattern":"HeadFinder ","errorType":"exception","errorClass":"NullPointerException","httpStatus":null,"severity":"error","filePath":"src/edu/stanford/nlp/trees/Tree.java","lineNumber":1178,"sourceCode":"    CoreLabel nodeLabel = (CoreLabel) label();\n\n    if (isLeaf()) {\n      return;\n    }\n\n    if (isPreTerminal()) {\n      nodeLabel.set(TreeCoreAnnotations.HeadWordLabelAnnotation.class, (CoreLabel) children()[0].label());\n      nodeLabel.set(TreeCoreAnnotations.HeadTagLabelAnnotation.class, nodeLabel);\n      return;\n    }\n\n    for (Tree kid : children()) {\n      kid.percolateHeadAnnotations(hf);\n    }\n\n    final Tree head = hf.determineHead(this);\n    if (head == null) {\n      throw new NullPointerException(\"HeadFinder \" + hf + \" returned null for \" + this);\n    } else if (head.isLeaf()) {\n      nodeLabel.set(TreeCoreAnnotations.HeadWordLabelAnnotation.class, (CoreLabel) head.label());\n      nodeLabel.set(TreeCoreAnnotations.HeadTagLabelAnnotation.class, (CoreLabel) head.parent(this).label());\n    } else if (head.isPreTerminal()) {\n      nodeLabel.set(TreeCoreAnnotations.HeadWordLabelAnnotation.class, (CoreLabel) head.children()[0].label());\n      nodeLabel.set(TreeCoreAnnotations.HeadTagLabelAnnotation.class, (CoreLabel) head.label());\n    } else {\n      if (!(head.label() instanceof CoreLabel)) {\n        throw new AssertionError(\"Horrible bug\");\n      }\n      CoreLabel headLabel = (CoreLabel) head.label();\n      nodeLabel.set(TreeCoreAnnotations.HeadWordLabelAnnotation.class, headLabel.get(TreeCoreAnnotations.HeadWordLabelAnnotation.class));\n      nodeLabel.set(TreeCoreAnnotations.HeadTagLabelAnnotation.class, headLabel.get(TreeCoreAnnotations.HeadTagLabelAnnotation.class));\n    }\n  }\n\n\n  /**","sourceCodeStart":1160,"sourceCodeEnd":1196,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/trees/Tree.java#L1160-L1196","documentation":"Thrown by Tree.percolateHeadAnnotations when the supplied HeadFinder's determineHead() returns null for a tree node. Stanford NLP requires every non-leaf node to have a determinable head; a null result means the HeadFinder implementation cannot handle the node's label or structure. It signals a broken/mismatched HeadFinder rather than bad input data per se.","triggerScenarios":"Calling percolateHeadAnnotations(hf) (directly or via headTerminal/headPreTerminal/dependencies pipelines) with a HeadFinder whose determineHead() returns null — e.g. a custom HeadFinder with no rule matching the node's label, or a head finder applied to trees with labels it does not recognize (e.g. ChineseHeadFinder on English trees).","commonSituations":"Custom HeadFinder implementations with incomplete rules; using a language-specific head finder on trees from another treebank; trees with unusual/terminal-only structure passed to annotation passes during parsing or dependency conversion.","solutions":["Use the correct language HeadFinder for the treebank (e.g. UniversalSemanticHeadFinder or CollinsHeadFinder for English PTB)","Check your custom HeadFinder's determineHead() and add a rule (plus a default) covering every non-terminal label in your trees","Inspect the tree printed in the message; remove or repair malformed nodes whose labels no head rule can match"],"exampleFix":"// before\ntree.percolateHeadAnnotations(new ChineseHeadFinder()); // English trees -> null head\n// after\ntree.percolateHeadAnnotations(new UniversalSemanticHeadFinder());","handlingStrategy":"validation","validationCode":"if (hf == null || tree == null) throw new IllegalArgumentException(\"need non-null HeadFinder and tree\");","typeGuard":"boolean usableHeadFinder(HeadFinder hf) { return hf != null; }","tryCatchPattern":"try { tree.percolateHeadAnnotations(hf); } catch (NullPointerException e) { log.warn(\"HeadFinder returned null head: {}\", e.getMessage()); }","preventionTips":["Pick a HeadFinder matching your treebank's language","Give custom HeadFinders a default head rule for unknown labels","Test annotation passes on a sample of your actual trees"],"tags":["nlp","parsing","headfinder","null-pointer"],"backgroundTag":"null-argument","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"}