stanfordnlp/CoreNLP · error · RuntimeException

Unknown grammatical relation '<grelString>' fields: <fields>

Error message

Unknown grammatical relation '<grelString>' fields: <fields>
Node: <node>
Known Grammatical relations: [<knownRelations>]

What it means

When reading a CoNLL-X file, the deprel string of each token is looked up in shortNameToGRel (the map of known short-name GrammaticalRelations for the current language, e.g. EnglishGrammaticalRelations). If the relation string is not recognized and is not the special case 'root', the reader throws this RuntimeException naming the unknown relation, the raw fields, the node, and the list of known relations.

Solutions

1. Check the 'Known Grammatical relations' list in the message and correct the deprel strings in the file to a supported name.
2. Use the language/universal GrammaticalStructure (e.g. UniversalEnglishGrammaticalStructure) matching the annotation scheme of your file.
3. Upgrade to a CoreNLP version whose relation set includes the relations used in your treebank, or register the missing relation if you have a custom GrammaticalRelations class.
4. Pre-map unsupported relations to nearest supported equivalents before parsing.

Example fix

// before: deprel column 'acl:relcl' with English (non-universal) reader
// after: parse with UniversalEnglishGrammaticalStructure.fromReader(...) which knows 'acl:relcl',
// or rewrite the column to 'relcl'

// Check deprel names against the known relation set before reading
Set<String> known = GrammaticalStructure.shortNameToGRel != null
  ? new HashSet<>(knownRelationShortNames) : null;
// or simply: verify every field 8 value is in the printed 'Known Grammatical relations' list

try {
  GrammaticalStructure gs = readCoNLLX(reader);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unknown grammatical relation")) {
    String rel = e.getMessage().split("'")[1];
    log.error("Unsupported deprel '" + rel + "'; remap or switch to the universal reader");
  } else throw e;
}

When it happens

Trigger: readCoNLLXGrammaticalStructure-style reading where a token's deprel column (field 8) contains a short name not present in the loaded language's GrammaticalRelations set; calling with a deprel that has wrong case beyond lowercasing, or a language-specific relation from a different treebank.

Common situations: Using CoNLL-X files annotated with universal or language-specific relations different from the loaded GrammaticalStructure language (e.g. UniversalEnglish relations fed to the English reader); typos like 'nsubjpass' vs 'nsubj:pass'; custom relations added in a newer CoreNLP release than the one in use.

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

• Error (line %d): 10 fields expected but %d are present
• Bad data format:
• Cannot find matching labelled span for {s}
• ERROR: typed SINGLETON feature.
• Bad number put into wordToNumber. Word is: \"" + input + "\

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

Appendix: source

Thrown at src/edu/stanford/nlp/trees/GrammaticalStructure.java:1159

    rootLabel.setValue("ROOT");
    rootLabel.setWord("ROOT");
    rootLabel.setIndex(0);
    IndexedWord dependencyRoot = new IndexedWord(rootLabel);
    for (int i = 0; i < tgWords.size(); i++) {
      String parentIdStr = tokenFields.get(i).get(CoNLLX_GovField);
      if (StringUtils.isNullOrEmpty(parentIdStr)) {
        continue;
      }
      String grelString = tokenFields.get(i).get(CoNLLX_RelnField);
      if (grelString.equals("null") || grelString.equals("erased"))
        continue;
      GrammaticalRelation grel = shortNameToGRel.get(grelString.toLowerCase());
      TypedDependency tdep;
      if (grel == null) {
        if (grelString.toLowerCase().equals("root")) {
          tdep = new TypedDependency(ROOT, dependencyRoot, tgWords.get(i));
        } else {
          throw new RuntimeException("Unknown grammatical relation '" +
                                     grelString + "' fields: " +
                                     tokenFields.get(i) + "\nNode: " +
                                     tgWords.get(i) + '\n' +
                                     "Known Grammatical relations: ["+shortNameToGRel.keySet() + ']');
        }
      } else {
        int parentId = Integer.parseInt(parentIdStr) - 1;
        if (parentId >= tgWords.size()) {
          System.err.printf("Warning: Invalid Parent Id %d Sentence Length: %d%n", parentId+1, tgWords.size());
          System.err.printf("         Assigning to root (0)%n");
          parentId = -1;
        }
        tdep = new TypedDependency(grel, (parentId == -1 ? dependencyRoot : tgWords.get(parentId)),
                                   tgWords.get(i));
      }
      tdeps.add(tdep);
    }
    return factory.build(tdeps, root);

View on GitHub (pinned to 1b7edd19c4)