stanfordnlp/CoreNLP · error · IllegalArgumentException

CoreMap must have either a Calendar or DocDate annotation

Error message

CoreMap must have either a Calendar or DocDate annotation

What it means

Before calling HeidelTime, the annotator requires the document's reference date via either CoreAnnotations.CalendarAnnotation or DocDateAnnotation. If neither key is present it throws IllegalArgumentException, since HeidelTime needs a publication date to resolve relative time expressions.

Solutions

1. Set CoreAnnotations.DocDateAnnotation (e.g. "2024-01-15") on the annotation before running HeidelTime.
2. Or set CoreAnnotations.CalendarAnnotation with a java.util.Calendar instance.
3. Include a preceding annotator/step (e.g. 'docdate' property) that infers the document date from metadata.
4. Add a pre-check in your code that fails fast with a clearer message when the date is missing.

Example fix

// before
Annotation ann = new Annotation(text);
heidelTime.annotate(ann); // throws
// after
Annotation ann = new Annotation(text);
ann.set(CoreAnnotations.DocDateAnnotation.class, "2024-01-15");
heidelTime.annotate(ann);

// Guard before invoking the annotator
if (!annotation.containsKey(CoreAnnotations.CalendarAnnotation.class) &&
    !annotation.containsKey(CoreAnnotations.DocDateAnnotation.class)) {
  annotation.set(CoreAnnotations.DocDateAnnotation.class, LocalDate.now().toString());
}

boolean hasDocDate(CoreMap doc) {
  return doc.containsKey(CoreAnnotations.CalendarAnnotation.class)
      || doc.containsKey(CoreAnnotations.DocDateAnnotation.class);
}

try {
  heidelTimeAnnotator.annotate(annotation);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Calendar or DocDate")) {
    annotation.set(CoreAnnotations.DocDateAnnotation.class, defaultDate);
    heidelTimeAnnotator.annotate(annotation);
  } else { throw e; }
}

When it happens

Trigger: Running HeidelTimeAnnotator on a CoreMap/Annotation created programmatically without setting the doc date; annotating raw text without a document-date pipeline stage supplying CalendarAnnotation or DocDateAnnotation.

Common situations: Building Annotation from a plain String in tests and calling the annotator directly; pipelines that omit the docdate annotator; streaming documents where the date metadata was dropped.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Array must be sorted!
• Can only operate on preterminals
• Cannot run Natural Logic forward entailment without…
• Cannot run OpenIE without a parse tree!
• CoreMap must have either a Calendar or DocDate annotation

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

Appendix: source

Thrown at src/edu/stanford/nlp/time/HeidelTimeAnnotator.java:92

      this.annotate((CoreMap)annotation);
    } catch (IOException e) {
      throw new RuntimeIOException(e);
    }
  }

  public void annotate(CoreMap document) throws IOException {
    //--Create Input File
    //(create file)
    File inputFile = File.createTempFile("heideltime", ".input");
    //(write to file)
    PrintWriter inputWriter = new PrintWriter(inputFile);
    inputWriter.println(document.get(CoreAnnotations.TextAnnotation.class));
    inputWriter.close();

    //--Get Date
    //(error checks)
    if(!document.containsKey(CoreAnnotations.CalendarAnnotation.class) && !document.containsKey(CoreAnnotations.DocDateAnnotation.class)){
      throw new IllegalArgumentException("CoreMap must have either a Calendar or DocDate annotation"); //not strictly necessary, technically...
    }
    //(variables)
    Calendar dateCalendar = document.get(CoreAnnotations.CalendarAnnotation.class);
    String pubDate = null;
    if (dateCalendar != null) {
      //(case: calendar annotation)
      pubDate = String.format("%TF", dateCalendar);
    } else {
      //(case: docdateannotation)
      String s = document.get(CoreAnnotations.DocDateAnnotation.class);
      if (s != null) {
        pubDate = s;
      }
    }

    //--Build Command
    ArrayList<String> args = new ArrayList<>();
    args.add("java");

View on GitHub (pinned to 1b7edd19c4)