stanfordnlp/CoreNLP · error · RuntimeException

Error occurred while constructing HeadFinder: " + e

Error message

Error occurred while constructing HeadFinder: " + e

What it means

TregexPattern's command-line main allows specifying a custom HeadFinder class (with optional constructor arguments). The class is loaded reflectively via Class.forName and instantiated via getConstructor(...).newInstance(...); any failure (class missing, no matching constructor, instantiation error) is rethrown as RuntimeException('Error occurred while constructing HeadFinder: ' + e).

Solutions

1. Verify the fully-qualified class name and that its jar is on the classpath
2. Check the HeadFinder class has a public constructor matching the supplied arguments (Strings)
3. Instantiate the HeadFinder in code first to see the underlying stack trace
4. Pass a HeadFinder programmatically instead of via the CLI flag

Example fix

// before
java ... TregexPattern -headFinder com.example.MyHF,extraArg pattern file
// after
java -cp .:myhf.jar ... TregexPattern -headFinder com.example.MyHF pattern file
// where MyHF has a public MyHF(String...) constructor

try {
  Class<?> c = Class.forName(headFinderClassName);
  if (!HeadFinder.class.isAssignableFrom(c)) throw new IllegalArgumentException(c + " is not a HeadFinder");
  c.getConstructor(String[].class);
} catch (ClassNotFoundException | NoSuchMethodException e) { /* fix name/classpath/constructor */ }

boolean isUsableHeadFinder(String name) {
  try { return HeadFinder.class.isAssignableFrom(Class.forName(name)); }
  catch (ClassNotFoundException e) { return false; }
}

try { TregexPattern.main(args); } catch (RuntimeException e) { if (e.getMessage().startsWith("Error occurred while constructing HeadFinder")) { e.printStackTrace(); /* check class name, classpath, constructor args */ } }

When it happens

Trigger: Running the TregexPattern main with -headFinder specifying a class that is not on the classpath, lacks a constructor matching the supplied String args, throws in its constructor, or is otherwise not instantiable as a HeadFinder.

Common situations: Typo in the fully-qualified class name; headfinder jar not on the classpath; changing a headfinder's constructor signature without updating CLI args; using a class that does not implement HeadFinder.

Related errors

• Couldn't create POS tagger extractor class
• Couldn't create POS tagger extractor class
• Error: illegal node code " + s
• args: treebankPath trainNums testNums
• Argument " + i + " to class constructor is null

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

Appendix: source

Thrown at src/edu/stanford/nlp/trees/tregex/TregexPattern.java:768

    } else if (argsMap.containsKey(yieldOnly)) {
      treePrintFormats.append("words,");
    } else {
      treePrintFormats.append("penn,");
    }
    if (argsMap.containsKey(uniqueTrees)) {
      TRegexTreeVisitor.printOnlyUniqueTrees = true;
    }

    HeadFinder hf = new CollinsHeadFinder();
    if(headFinderClassName != null) {
      Class[] hfArgClasses = new Class[headFinderArgs.length];
      for (int i = 0; i < hfArgClasses.length; i++) {
        hfArgClasses[i] = String.class;
      }
      try {
        hf = (HeadFinder) Class.forName(headFinderClassName).getConstructor(hfArgClasses).newInstance((Object[]) headFinderArgs); // cast to Object[] necessary to avoid varargs-related warning.
      }
      catch(Exception e) { throw new RuntimeException("Error occurred while constructing HeadFinder: " + e); }
    }

    TRegexTreeVisitor.tp = new TreePrint(treePrintFormats.toString(), new PennTreebankLanguagePack());

    try {
      //TreePattern p = TreePattern.compile("/^S/ > S=dt $++ '' $-- ``");
      TregexPatternCompiler tpc = new TregexPatternCompiler(hf);
      Macros.addAllMacros(tpc, macroFilename, encoding);
      TregexPattern p = tpc.compile(matchString);
      errPW.println("Pattern string:\n" + p.pattern());
      errPW.println("Parsed representation:");
      p.prettyPrint(errPW);

      String[] handles = argsMap.get(printHandleOption);
      if (argsMap.containsKey("-filter")) {
        TreeReaderFactory trf = getTreeReaderFactory(treeReaderFactoryClassName);
        treebank = new MemoryTreebank(trf, encoding);//has to be in memory since we're not storing it on disk
        //read from stdin

View on GitHub (pinned to 1b7edd19c4)