stanfordnlp/CoreNLP · error · IllegalStateException

ERROR: invalid direction type

Error message

ERROR: invalid direction type

What it means

Head rules are encoded as arrays whose first element is a direction keyword (left, right, leftdis, rightdis, lefthead, righthead, leftexcept, rightexcept, etc.). traverseLocate switches on that keyword and throws IllegalStateException when how[0] is not one of the recognized direction types, meaning the rule table was populated with an invalid operation string.

Solutions

  1. Fix the direction keyword in the nonTerminalInfo rule to a supported value (left, right, leftdis, rightdis, leftheaddis, rightheaddis, leftexcept, rightexcept, etc.).
  2. Compare against valid keywords in AbstractCollinsHeadFinder's switch (postureLookup) in the same file.
  3. Ensure rule arrays are ordered [direction, ...categories] with no off-by-one shift.

Example fix

// before
nonTerminalInfo.put("NP", new String[][]{{"leftmost", "NN", "NNS"}});
// after
nonTerminalInfo.put("NP", new String[][]{{"left", "NN", "NNS"}});
Defensive patterns

Strategy: validation

Validate before calling

Set<String> VALID = Set.of("left","right","leftdis","rightdis","lefthand","righthand","leftexcept","rightexcept","left","right"); for (String[] rule : rules) { assert VALID.contains(rule[0]); }

Try / catch

try { head = hf.determineHead(t, parent); } catch (IllegalStateException e) { throw new ConfigurationException("Bad head rule: " + e.getMessage(), e); }

Prevention

When it happens

Trigger: A subclass of AbstractCollinsHeadFinder (or code built via tregex/tsurgeon-derived configuration) puts a rule into nonTerminalInfo whose direction element is misspelled or unsupported, and determineHead/traverseLocate then evaluates that rule.

Common situations: Typo in a hand-written head rule (e.g. 'leftmost' instead of 'left'); porting rules from another head finder with different keywords; a subclasses' rule array shifted so how[0] holds a category instead of a direction.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at src/edu/stanford/nlp/trees/AbstractCollinsHeadFinder.java:290

        headIdx = findLeftHead(daughterTrees, how);
        break;
      case "leftdis":
        headIdx = findLeftDisHead(daughterTrees, how);
        break;
      case "leftexcept":
        headIdx = findLeftExceptHead(daughterTrees, how);
        break;
      case "right":
        headIdx = findRightHead(daughterTrees, how);
        break;
      case "rightdis":
        headIdx = findRightDisHead(daughterTrees, how);
        break;
      case "rightexcept":
        headIdx = findRightExceptHead(daughterTrees, how);
        break;
      default:
        throw new IllegalStateException("ERROR: invalid direction type " + how[0] + " to nonTerminalInfo map in AbstractCollinsHeadFinder.");
    }

    // what happens if our rule didn't match anything
    if (headIdx < 0) {
      if (lastResort) {
        // use the default rule to try to match anything except categoriesToAvoid
        // if that doesn't match, we'll return the left or rightmost child (by
        // setting headIdx).  We want to be careful to ensure that postOperationFix
        // runs exactly once.
        String[] rule;
        if (how[0].startsWith("left")) {
          headIdx = 0;
          rule = defaultLeftRule;
        } else {
          headIdx = daughterTrees.length - 1;
          rule = defaultRightRule;
        }
        Tree child = traverseLocate(daughterTrees, rule, false);

View on GitHub (pinned to 1b7edd19c4)