stanfordnlp/CoreNLP · error · IllegalStateException

The annotator header property is set to true, but a…

Error message

The annotator header property is set to true, but a different option has been provided for mapping file: ${mappingLine}

What it means

When the mapping.header property is 'true', the annotator derives header fields from each mapping file, and each mapping line must either omit header options (getting the implicit 'header=true') or explicitly set header=true. If a mapping line contains a header option set to something other than true, IllegalStateException is thrown because the two settings contradict each other.

Solutions

Remove 'header=false' (or any non-true header option) from the offending mapping line so the global header=true applies.
Set mapping.header=false and instead declare header fields explicitly via mapping.header.fieldnames if some files lack headers.
Make all mapping lines consistent: either all rely on global header=true or none carry header options.
Check the mappingLine named in the message to find exactly which entry conflicts.

Example fix

// before
props.setProperty("tokensregexner.rules.mapping", "header=false, rules1.tab");
props.setProperty("tokensregexner.rules.mapping.header", "true");
// after
props.setProperty("tokensregexner.rules.mapping", "rules1.tab");
props.setProperty("tokensregexner.rules.mapping.header", "true");

Defensive patterns

Strategy: validation

Validate before calling

if ("true".equalsIgnoreCase(props.getProperty("tokensregexner.rules.mapping.header","true"))) {
  for (String m : props.getProperty("tokensregexner.rules.mapping","").split(","))
    if (m.trim().matches(".*header\\s*=\\s*(?!true\\b).*")) throw new IllegalStateException("Conflicting header option in mapping: " + m);
}

Type guard

boolean mappingHeaderConflicts(String line) { return line != null && line.toLowerCase().contains("header") && !java.util.regex.Pattern.compile("header\\s*=\\s*true").matcher(line.toLowerCase()).find(); }

Try / catch

try { new TokensRegexNERAnnotator(name, props); } catch (IllegalStateException e) { if (e.getMessage().contains("header property is set to true")) { log.error("Fix mapping line: " + e.getMessage()); } throw e; }

Prevention

Keep header configuration in exactly one place (global flag or per-file, not both)
Lint mapping strings for stray header=false entries
Version-control annotator configs and review mapping edits carefully

When it happens

Trigger: Setting mapping.header=true while a mapping file line (in the comma-separated mapping list) contains header=false or header=other-value, e.g. 'header=false, rules1.tab'.

Common situations: Mixing configs where the global header flag was switched to true but an old per-file 'header=false' remained; hand-editing mapping strings; combining mapping files with different header conventions.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

            + ": Error opening the common words file: " + commonWordsFile, ex);
      }
    }

    String headerProp = properties.getProperty(prefix + "mapping.header", defaultHeader);
    boolean readHeaderFromFile = headerProp.equalsIgnoreCase("true");
    String[] annotationFieldnames = null;
    String[] headerFields = null;
    if (readHeaderFromFile) {
      annotationFieldnames = StringUtils.EMPTY_STRING_ARRAY;
      annotationFields = new ArrayList<>();
      // Set the read header property of each file to true
      for (int i = 0; i < mappings.length; i++) {
        String mappingLine = mappings[i];
        if ( ! mappingLine.contains("header")) {
          mappingLine = "header=true, " + mappingLine;
          mappings[i] = mappingLine;
        } else if ( ! Pattern.compile("header\\s*=\\s*true").matcher(mappingLine.toLowerCase()).find()) {
          throw new IllegalStateException("The annotator header property is set to true, but a different option has been provided for mapping file: " + mappingLine);
        }
      }

    } else {
      headerFields = COMMA_DELIMITERS_PATTERN.split(headerProp);
      // Take header fields and remove known headers to get annotation field names
      List<String> fieldNames = new ArrayList<>();
      List<Class> fieldClasses = new ArrayList<>();
      for (String field : headerFields) {
        if ( ! predefinedHeaderFields.contains(field)) {
          Class fieldClass = EnvLookup.lookupAnnotationKeyWithClassname(null, field);
          if (fieldClass == null) {
            // check our properties
            String classname = properties.getProperty(prefix + "mapping.field." + field);
            fieldClass = EnvLookup.lookupAnnotationKeyWithClassname(null, classname);
          }
          if (fieldClass != null) {
            fieldNames.add(field);

View on GitHub (pinned to 1b7edd19c4)