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

getPubDate extracts the document creation time to pass as -dct to HeidelTime, and requires the CoreMap to carry either a CalendarAnnotation or a DocDateAnnotation. If neither key is present it throws an IllegalArgumentException, even though the doc date is technically optional for HeidelTime.

Solutions

Add the 'docdate' capability to the pipeline (e.g. include 'cleanxml,tokenize,ssplit,pos' and ensure the document carries a DocDateAnnotation), or run the date-annotating stage before heideltimekb
Set the date explicitly: annotation.set(CoreAnnotations.DocDateAnnotation.class, "2011-04-12") or call annotation.setDate(Calendar) before annotating
Provide a default date in code when none is present, if approximate DCT is acceptable

Example fix

// before
Annotation doc = new Annotation(text);
pipeline.annotate(doc);
// after
Annotation doc = new Annotation(text);
doc.set(CoreAnnotations.DocDateAnnotation.class, "2011-04-12");
pipeline.annotate(doc);

Defensive patterns

Strategy: validation

Validate before calling

// Before running the heideltimekb annotator
if (!annotation.containsKey(CoreAnnotations.CalendarAnnotation.class)
    && !annotation.containsKey(CoreAnnotations.DocDateAnnotation.class)) {
    annotation.set(CoreAnnotations.DocDateAnnotation.class, "2011-04-12"); // or your document's known date
}

Try / catch

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

Prevention

Always run a pipeline stage that sets DocDateAnnotation (or setDate) before heideltimekb
Set DocDateAnnotation explicitly when constructing Annotations programmatically
Order the annotators so date-annotating stages precede heideltimekb
Note the code comment: the check is 'not strictly necessary' — supplying a default DCT avoids it entirely

When it happens

Trigger: Invoking HeidelTimeKBPAnnotator.annotate on a document that was not first processed by annotators that set the document date — i.e. a pipeline without 'cleanxml'+'tokenize,ssplit' feeding a docdate, or manual Annotation construction without setDate/DocDateAnnotation.

Common situations: Building Annotations programmatically without docdate; running the heideltimekb annotator first in the pipeline or dropping the ssplit/date-producing stages; KBP pipelines that omit the docdate requirement.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/edu/stanford/nlp/time/HeidelTimeKBPAnnotator.java:129

      String output = outputWriter.getBuffer().toString();
      List<CoreMap> timexAnns = outputReader.process(document, output);

      document.set(TimeAnnotations.TimexAnnotations.class, timexAnns);
      if (outputResults) {
        System.out.println(timexAnns);
      }
    } catch (Exception e) {
      e.printStackTrace(System.err);
      System.err.println("error running HeidelTime on this doc: "+document.get(CoreAnnotations.DocIDAnnotation.class));
//      throw e;
    }
  }

  private Optional<String> getPubDate(CoreMap document) {
    //--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);
    if (dateCalendar != null) {
      //(case: calendar annotation)
      return Optional.of(String.format("%TF", dateCalendar));
    } else {
      //(case: docdateannotation)
      String s = document.get(CoreAnnotations.DocDateAnnotation.class);
      if (s != null) {
        return Optional.of(s);
      }
    }
    return Optional.empty();
  }

  private void prepareHeidelTimeInput(PrintWriter stream, CoreMap document) {
    // We really should use the full text annotation because our cleanxml can be useless.

View on GitHub (pinned to 1b7edd19c4)