stanfordnlp/CoreNLP · error · SsurgeonParseException

SplitWord expected a -headIndex, 0-indexed for the word…

Error message

SplitWord expected a -headIndex, 0-indexed for the word piece to use when chopping up the word

What it means

SplitWord must know which piece becomes the head of the re-attached dependency subtree; this is given by the 0-indexed -headIndex argument. If headIndex is null, the constructor throws SsurgeonParseException.

Solutions

  1. Add -headIndex N (0-indexed) pointing at the piece that should inherit the original head relation, e.g. -headIndex 0
  2. Pass a non-null Integer as the headIndex constructor parameter
  3. Double-check that N is within range: 0 <= N < nodePieces.size() to avoid later index errors

Example fix

// before
new SplitWord("w", pieces, null, reln, null, true);
// after
new SplitWord("w", pieces, 0, reln, null, true); // first piece is the head
Defensive patterns

Strategy: validation

Validate before calling

if (headIndex == null || headIndex < 0 || headIndex >= nodePieces.size()) throw new IllegalArgumentException("-headIndex must be a 0-based index into the pieces");

Try / catch

try { SplitWord sw = new SplitWord(node, pieces, headIndex, reln, names, exact); } catch (SsurgeonParseException e) { log.error("Missing -headIndex: " + e.getMessage()); }

Prevention

When it happens

Trigger: Constructing SplitWord without the -headIndex flag (or passing null Integer as the third constructor argument).

Common situations: Writing an ssurgeon rule and omitting -headIndex because it seems optional; a null Integer auto-boxed from an unparsed command-line value; copying an older SplitWord invocation predating the headIndex argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/edu/stanford/nlp/semgraph/semgrex/ssurgeon/SplitWord.java:72

    if (nodePieces == null || nodePieces.size() == 0) {
      throw new SsurgeonParseException("SplitWord expected -exact or -regex with regex to determine which pieces to split the word into");
    }
    if (nodePieces.size() == 1) {
      throw new SsurgeonParseException("SplitWord expected at least two -exact or -regex");
    }
    if (exactSplit) {
      this.exactPieces = new ArrayList<>(nodePieces);
      this.nodeRegex = null;
    } else {
      this.nodeRegex = new ArrayList<>();
      for (int i = 0; i < nodePieces.size(); ++i) {
        this.nodeRegex.add(Pattern.compile(nodePieces.get(i)));
      }
      this.exactPieces = null;
    }

    if (headIndex == null) {
      throw new SsurgeonParseException("SplitWord expected a -headIndex, 0-indexed for the word piece to use when chopping up the word");
    }
    this.headIndex = headIndex;

    if (relation == null) {
      throw new SsurgeonParseException("SplitWord expected a -reln to represent the dependency to use for the new words");
    }
    this.relation = relation;

    if (nodeNames != null) {
      String[] namePieces = nodeNames.split(",");
      this.nodeNames = new HashMap<>();
      for (String namePiece : namePieces) {
        String[] pieces = namePiece.split("=", 2);
        if (pieces.length < 2) {
          throw new SsurgeonParseException("SplitWord got a -name parameter which did not have a number for one of the names.  Should look like 0=foo,1=bar");
        }
        int idx = Integer.valueOf(pieces[0]);
        if (idx >= nodePieces.size()) {

View on GitHub (pinned to 1b7edd19c4)