stanfordnlp/CoreNLP · error · IllegalStateException

Season start month is unknown

Error message

Season start month is unknown

What it means

When converting a time range to a TIMEX3-style value string, a season's starting month is mapped to SU/FA etc. via a switch. If the season start month falls outside the enumerated cases (1=WInter,4=SP,6=SU,9=FA in this region), the code cannot represent it and throws an IllegalStateException.

Solutions

  1. Inspect the begin Partial's monthOfYear that produced the season start; fix the interval/range computation so season anchors land on supported months.
  2. Normalize the range before formatting (e.g. snap season starts to the nearest supported anchor month).
  3. If new season boundaries are legitimately needed, extend the switch with additional month cases.

Example fix

// before
default:
  throw new IllegalStateException("Season start month is unknown");
// after
default:
  int m = begin.getMonthOfYear();
  if (m >= 10 || m <= 2) { value.append("WI"); }
  else { value.append("SP"); }
  break;
Defensive patterns

Strategy: try-catch

Validate before calling

if (begin.get(DateTimeFieldType.monthOfYear()) != 1 && begin.get(DateTimeFieldType.monthOfYear()) != 4
    && begin.get(DateTimeFieldType.monthOfYear()) != 6 && begin.get(DateTimeFieldType.monthOfYear()) != 9) {
  // season anchor unsupported — normalize range first
}

Try / catch

try {
  String v = JodaTimeUtils.convertRangeToString(begin, end, opts);
} catch (IllegalStateException e) {
  logger.warning("Unrepresentable season range: " + e.getMessage());
  // fall back to explicit date range formatting
}

Prevention

When it happens

Trigger: Calling the range-to-string formatting method (e.g. convertRangeToString / toTimexValue) on a Partial range whose computed season start month is not 1, 4, 6, or 9 — typically from inconsistent month/week fields or a buggy interval calculation in the input Partials.

Common situations: Unusual date ranges (e.g. spanning months that yield a season boundary of month 3 or 12) fed into SUTime range formatting; corrupted or synthetic Partial values with monthOfYear outside the expected season anchors.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at src/edu/stanford/nlp/time/JodaTimeUtils.java:978

        //(case: quarter of year)
        value.append("Q").append(( begin.getMonthOfYear()-1) / 3 + 1);
      } else if(monthTerminal && monthDiff == 3 && begin.getMonthOfYear() % 3 == 0){
        //(case: season)
        switch( begin.getMonthOfYear() ){
          case 12:
            value.append("WI");
            break;
          case 3:
            value.append("SP");
            break;
          case 6:
            value.append("SU");
            break;
          case 9:
            value.append("FA");
            break;
          default:
            throw new IllegalStateException("Season start month is unknown");
        }
      } else if(weekTerminal && weekDiff == 1) {
        //(case: a week)
        value.append("W").append(zeroPad(begin.getWeekOfWeekyear(), 2));
      } else if(monthTerminal && monthDiff == 1 && weekDiff != 1 || opts.forceDate) {
        //(case: a month)
        value.append( zeroPad(begin.getMonthOfYear(),2) );
      } else {
        //(case: treat as duration)
        return timexDurationValue(begin, end);
      }
      return value.toString();
    } else if(noFurtherFields(dayOfWeek(), begin, end) && dayDiff == 2 && begin.getDayOfWeek() == 6){
      //(case: a weekend)
      value.append("W").append(zeroPad(begin.getWeekOfWeekyear(),2)).append("-WE");
      return value.toString();
    } else if(dayDiff < maximumValue(dayOfMonth(),begin) || opts.forceDate) {
      //(case: month and more)

View on GitHub (pinned to 1b7edd19c4)