{"record":{"id":"d42b306c1df5a40e","repo":"stanfordnlp/CoreNLP","slug":"not-recognized-annotation-class-field-in-header","errorCode":null,"errorMessage":"Not recognized annotation class field \"\" in header for mapping file ","messagePattern":"Not recognized annotation class field \"\" in header for mapping file ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/edu/stanford/nlp/pipeline/TokensRegexNERAnnotator.java","lineNumber":933,"sourceCode":"                String[] headerItems = header.split(\"\\\\s+\");\n                headerSet = true;\n\n                if (headerItems.length == 1 && headerItems[0].equalsIgnoreCase(\"true\")) {\n                  try (BufferedReader br = IOUtils.readerFromString(filePath)) {\n                    String headerLine = br.readLine();\n                    headerItems = headerLine.split(\"\\\\t\");\n                  } catch (IOException e) {\n                    logger.err(e);\n                  }\n                }\n\n                headerList.add(headerItems);\n\n                for (String field : headerItems) {\n                  if (!predefinedHeaderFields.contains(field) && !Arrays.asList(annotationFieldnames).contains(field)) {\n                    Class fieldClass = EnvLookup.lookupAnnotationKeyWithClassname(null, field);\n                    if (fieldClass == null) {\n                      throw new RuntimeException( \"Not recognized annotation class field \\\"\" + field + \"\\\" in header for mapping file \" + allOptions[numOptions -1]);\n                    }\n                    else {\n                      annotationFields.add(fieldClass);\n                      annotationFieldnames = Arrays.copyOf(annotationFieldnames, annotationFieldnames.length + 1);\n                      annotationFieldnames[annotationFieldnames.length - 1] = field;\n                    }\n                  }\n                }\n                break;\n\n              default:\n                break;\n            }\n          }\n        }\n        mappings[index] = allOptions[numOptions-1];\n      }\n","sourceCodeStart":915,"sourceCodeEnd":951,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/pipeline/TokensRegexNERAnnotator.java#L915-L951","documentation":"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.","triggerScenarios":"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\tdescription' where 'description' is not an Annotation Key.","commonSituations":"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.","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"],"exampleFix":"// before (mapping file header)\nword\t Smith      Smith  U-PERSON\n// after\nwords\toverwrite\tnerpattern\tnertype\nSmith\tU-PERSON\t/Smith/\tPERSON","handlingStrategy":"validation","validationCode":"// Validate mapping file header before loading\nSet<String> allowed = Set.of(\"words\", \"pattern\", \"overwrite\", \"word\", \"tag\", \"ner\", \"normalized\");\ntry (BufferedReader br = Files.newBufferedReader(Paths.get(mappingFile))) {\n  String[] header = br.readLine().split(\"\\\\t\");\n  for (String field : header) {\n    String f = field.trim();\n    if (!allowed.contains(f))\n      throw new IllegalStateException(\"Unknown header field '\" + f + \"' in \" + mappingFile);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  pipeline = new StanfordCoreNLP(props);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Not recognized annotation class field\")) {\n    log.error(\"Mapping file header has unknown field: \" + e.getMessage());\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["configuration","file-format","tokensregexner"],"backgroundTag":"schema-validation-failed","analyzedSha":"1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a","analyzedAt":"2026-09-10T02:24:07.274Z","contentChangedAt":"2026-09-10T02:24:07.274Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}