{"record":{"id":"07ae12b886eb8e82","repo":"stanfordnlp/CoreNLP","slug":"coremap-must-have-either-a-calendar-or-docdate-ann-07ae12","errorCode":null,"errorMessage":"CoreMap must have either a Calendar or DocDate annotation","messagePattern":"CoreMap must have either a Calendar or DocDate annotation","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/edu/stanford/nlp/time/HeidelTimeKBPAnnotator.java","lineNumber":129,"sourceCode":"      String output = outputWriter.getBuffer().toString();\n      List<CoreMap> timexAnns = outputReader.process(document, output);\n\n      document.set(TimeAnnotations.TimexAnnotations.class, timexAnns);\n      if (outputResults) {\n        System.out.println(timexAnns);\n      }\n    } catch (Exception e) {\n      e.printStackTrace(System.err);\n      System.err.println(\"error running HeidelTime on this doc: \"+document.get(CoreAnnotations.DocIDAnnotation.class));\n//      throw e;\n    }\n  }\n\n  private Optional<String> getPubDate(CoreMap document) {\n    //--Get Date\n    //(error checks)\n    if (!document.containsKey(CoreAnnotations.CalendarAnnotation.class) && !document.containsKey(CoreAnnotations.DocDateAnnotation.class)) {\n      throw new IllegalArgumentException(\"CoreMap must have either a Calendar or DocDate annotation\"); //not strictly necessary, technically...\n    }\n    //(variables)\n    Calendar dateCalendar = document.get(CoreAnnotations.CalendarAnnotation.class);\n    if (dateCalendar != null) {\n      //(case: calendar annotation)\n      return Optional.of(String.format(\"%TF\", dateCalendar));\n    } else {\n      //(case: docdateannotation)\n      String s = document.get(CoreAnnotations.DocDateAnnotation.class);\n      if (s != null) {\n        return Optional.of(s);\n      }\n    }\n    return Optional.empty();\n  }\n\n  private void prepareHeidelTimeInput(PrintWriter stream, CoreMap document) {\n    // We really should use the full text annotation because our cleanxml can be useless.","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/time/HeidelTimeKBPAnnotator.java#L111-L147","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nAnnotation doc = new Annotation(text);\npipeline.annotate(doc);\n// after\nAnnotation doc = new Annotation(text);\ndoc.set(CoreAnnotations.DocDateAnnotation.class, \"2011-04-12\");\npipeline.annotate(doc);","handlingStrategy":"validation","validationCode":"// Before running the heideltimekb annotator\nif (!annotation.containsKey(CoreAnnotations.CalendarAnnotation.class)\n    && !annotation.containsKey(CoreAnnotations.DocDateAnnotation.class)) {\n    annotation.set(CoreAnnotations.DocDateAnnotation.class, \"2011-04-12\"); // or your document's known date\n}","typeGuard":null,"tryCatchPattern":"try {\n    pipeline.annotate(annotation);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Calendar or DocDate\")) {\n        annotation.set(CoreAnnotations.DocDateAnnotation.class, \"1970-01-01\");\n        pipeline.annotate(annotation);\n    } else { throw e; }\n}","preventionTips":["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"],"tags":["java","nlp","illegal-argument","missing-annotation"],"backgroundTag":"missing-required-argument","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"}