stanfordnlp/CoreNLP · error · RuntimeException

Not recognized annotation class field "" in header for…

Error message

Not recognized annotation class field "" in header for mapping file

What it means

TokensRegexNERAnnotator validates the header of each mapping file. Header fields must be one of the predefined fields (like words, pattern, overwrite) or a known CoreMap annotation key resolvable via EnvLookup.lookupAnnotationKeyWithClassname. An unrecognized column name causes this RuntimeException when the mapping file is loaded.

Solutions

Fix the mapping file header to use only predefined fields (words, pattern, overwrite, etc.) or valid CoreAnnotations field names (word, tag, ner, normalized, ...)
If a custom field is needed, register its annotation key class in the TokensRegex environment so EnvLookup can resolve it
Check for hidden characters (BOM, extra spaces, tabs) corrupting the field name in the header line
Verify the correct file is being loaded — the exception names the mapping file path

Example fix

// before (mapping file header)
word	 Smith      Smith  U-PERSON
// after
words	overwrite	nerpattern	nertype
Smith	U-PERSON	/Smith/	PERSON

Defensive patterns

Strategy: validation

Validate before calling

// Validate mapping file header before loading
Set<String> allowed = Set.of("words", "pattern", "overwrite", "word", "tag", "ner", "normalized");
try (BufferedReader br = Files.newBufferedReader(Paths.get(mappingFile))) {
  String[] header = br.readLine().split("\\t");
  for (String field : header) {
    String f = field.trim();
    if (!allowed.contains(f))
      throw new IllegalStateException("Unknown header field '" + f + "' in " + mappingFile);
  }
}

Try / catch

try {
  pipeline = new StanfordCoreNLP(props);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("Not recognized annotation class field")) {
    log.error("Mapping file header has unknown field: " + e.getMessage());
  }
  throw e;
}

Prevention

Keep mapping file headers limited to documented predefined fields or known CoreAnnotations names
Strip BOM and trailing whitespace from header lines
Register custom annotation keys in the TokensRegex environment if custom fields are needed
Validate headers in CI with a small script that checks each column name

When it happens

Trigger: The first line of a mapping file contains a column name that is neither a predefined header field nor a resolvable annotation class field name, e.g. a header 'word description' where 'description' is not an Annotation Key.

Common situations: Hand-editing TSV rules and inventing column names, renaming an existing annotation field, using a custom annotation class that was never registered with the environment (via a TokensRegex env file), or a stray BOM/whitespace making a valid field name unrecognizable.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/edu/stanford/nlp/pipeline/TokensRegexNERAnnotator.java:933

                String[] headerItems = header.split("\\s+");
                headerSet = true;

                if (headerItems.length == 1 && headerItems[0].equalsIgnoreCase("true")) {
                  try (BufferedReader br = IOUtils.readerFromString(filePath)) {
                    String headerLine = br.readLine();
                    headerItems = headerLine.split("\\t");
                  } catch (IOException e) {
                    logger.err(e);
                  }
                }

                headerList.add(headerItems);

                for (String field : headerItems) {
                  if (!predefinedHeaderFields.contains(field) && !Arrays.asList(annotationFieldnames).contains(field)) {
                    Class fieldClass = EnvLookup.lookupAnnotationKeyWithClassname(null, field);
                    if (fieldClass == null) {
                      throw new RuntimeException( "Not recognized annotation class field \"" + field + "\" in header for mapping file " + allOptions[numOptions -1]);
                    }
                    else {
                      annotationFields.add(fieldClass);
                      annotationFieldnames = Arrays.copyOf(annotationFieldnames, annotationFieldnames.length + 1);
                      annotationFieldnames[annotationFieldnames.length - 1] = field;
                    }
                  }
                }
                break;

              default:
                break;
            }
          }
        }
        mappings[index] = allOptions[numOptions-1];
      }

View on GitHub (pinned to 1b7edd19c4)