{"record":{"id":"5128f26e07e14287","repo":"stanfordnlp/CoreNLP","slug":"coremap-must-have-either-a-calendar-or-docdate-ann","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/HeidelTimeAnnotator.java","lineNumber":92,"sourceCode":"      this.annotate((CoreMap)annotation);\n    } catch (IOException e) {\n      throw new RuntimeIOException(e);\n    }\n  }\n\n  public void annotate(CoreMap document) throws IOException {\n    //--Create Input File\n    //(create file)\n    File inputFile = File.createTempFile(\"heideltime\", \".input\");\n    //(write to file)\n    PrintWriter inputWriter = new PrintWriter(inputFile);\n    inputWriter.println(document.get(CoreAnnotations.TextAnnotation.class));\n    inputWriter.close();\n\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    String pubDate = null;\n    if (dateCalendar != null) {\n      //(case: calendar annotation)\n      pubDate = String.format(\"%TF\", dateCalendar);\n    } else {\n      //(case: docdateannotation)\n      String s = document.get(CoreAnnotations.DocDateAnnotation.class);\n      if (s != null) {\n        pubDate = s;\n      }\n    }\n\n    //--Build Command\n    ArrayList<String> args = new ArrayList<>();\n    args.add(\"java\");","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/stanfordnlp/CoreNLP/blob/1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a/src/edu/stanford/nlp/time/HeidelTimeAnnotator.java#L74-L110","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set CoreAnnotations.DocDateAnnotation (e.g. \"2024-01-15\") on the annotation before running HeidelTime.","Or set CoreAnnotations.CalendarAnnotation with a java.util.Calendar instance.","Include a preceding annotator/step (e.g. 'docdate' property) that infers the document date from metadata.","Add a pre-check in your code that fails fast with a clearer message when the date is missing."],"exampleFix":"// before\nAnnotation ann = new Annotation(text);\nheidelTime.annotate(ann); // throws\n// after\nAnnotation ann = new Annotation(text);\nann.set(CoreAnnotations.DocDateAnnotation.class, \"2024-01-15\");\nheidelTime.annotate(ann);","handlingStrategy":"validation","validationCode":"// Guard before invoking the annotator\nif (!annotation.containsKey(CoreAnnotations.CalendarAnnotation.class) &&\n    !annotation.containsKey(CoreAnnotations.DocDateAnnotation.class)) {\n  annotation.set(CoreAnnotations.DocDateAnnotation.class, LocalDate.now().toString());\n}","typeGuard":"boolean hasDocDate(CoreMap doc) {\n  return doc.containsKey(CoreAnnotations.CalendarAnnotation.class)\n      || doc.containsKey(CoreAnnotations.DocDateAnnotation.class);\n}","tryCatchPattern":"try {\n  heidelTimeAnnotator.annotate(annotation);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"Calendar or DocDate\")) {\n    annotation.set(CoreAnnotations.DocDateAnnotation.class, defaultDate);\n    heidelTimeAnnotator.annotate(annotation);\n  } else { throw e; }\n}","preventionTips":["Always set a document date (DocDateAnnotation) when constructing Annotations for temporal processing.","Include a docdate-inference stage in your pipeline configuration.","For tests, build a helper that attaches today's date to every new Annotation."],"tags":["java","missing-annotation","heideltime","precondition"],"backgroundTag":"missing-required-config-field","analyzedSha":"1b7edd19c4d0d7b1f13a2591425b9b60a0b1af7a","analyzedAt":"2026-09-10T02:24:07.274Z","contentChangedAt":"2026-09-10T02:24:07.274Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}