flowable/flowable-engine · error · java.text.ParseException

Month values must be between 1 and 12

Error message

Month values must be between 1 and 12

What it means

CronExpression validates the MONTH field while parsing: month values and range ends must be 1-12 (JAN-DEC names are mapped to numbers before this check); the '*' sentinel is exempt. Out-of-range values make new CronExpression(String) throw a java.text.ParseException with this message.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/calendar/CronExpression.java:989

    protected void addToSet(int val, int end, int incr, int type) throws ParseException {

        TreeSet<Integer> set = getSet(type);

        if (type == SECOND || type == MINUTE) {
            if ((val < 0 || val > 59 || end > 59) && (val != ALL_SPEC_INT)) {
                throw new ParseException("Minute and Second values must be between 0 and 59", -1);
            }
        } else if (type == HOUR) {
            if ((val < 0 || val > 23 || end > 23) && (val != ALL_SPEC_INT)) {
                throw new ParseException("Hour values must be between 0 and 23", -1);
            }
        } else if (type == DAY_OF_MONTH) {
            if ((val < 1 || val > 31 || end > 31) && (val != ALL_SPEC_INT) && (val != NO_SPEC_INT)) {
                throw new ParseException("Day of month values must be between 1 and 31", -1);
            }
        } else if (type == MONTH) {
            if ((val < 1 || val > 12 || end > 12) && (val != ALL_SPEC_INT)) {
                throw new ParseException("Month values must be between 1 and 12", -1);
            }
        } else if (type == DAY_OF_WEEK) {
            if ((val == 0 || val > 7 || end > 7) && (val != ALL_SPEC_INT) && (val != NO_SPEC_INT)) {
                throw new ParseException("Day-of-Week values must be between 1 and 7", -1);
            }
        }

        if ((incr == 0 || incr == -1) && val != ALL_SPEC_INT) {
            if (val != -1) {
                set.add(val);
            } else {
                set.add(NO_SPEC);
            }

            return;
        }

        int startAt = val;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Correct the month token to 1-12, or use month abbreviations (JAN-DEC) to avoid ambiguity.
2. When building the string from java.util.Calendar, add 1 to calendar.get(Calendar.MONTH) before inserting.
3. Check field order: 6-field expressions are sec min hour day month dow — the month is the 5th field.
4. Pre-validate with CronExpression.isValidExpression() before persisting the configuration.

Example fix

// before
int monthZeroBased = Calendar.getInstance().get(Calendar.MONTH); // 0-11
CronExpression expr = new CronExpression("0 0 0 1 " + monthZeroBased + " ?");
// after
int month = Calendar.getInstance().get(Calendar.MONTH) + 1; // 1-12
CronExpression expr = new CronExpression("0 0 0 1 " + month + " ?");

int m = calendar.get(Calendar.MONTH) + 1; // Calendar months are 0-based
if (m < 1 || m > 12) throw new IllegalStateException("bad month");
String cron = "0 0 0 1 " + m + " ?";

try {
    CronExpression expr = new CronExpression(cron);
} catch (ParseException e) {
    throw new ConfigurationException("Invalid month field in cron: " + cron, e);
}

When it happens

Trigger: new CronExpression(cronString) with a month token of 0 or >12, e.g. '0 0 0 1 13 ?' or '0 0 0 1 0 ?'. Also a range end >12 like '0 0 0 1 10-13 ?'.

Common situations: Zero-based month generation from java.util.Calendar (which returns 0-11) concatenated into a cron string; confused field order (a day-of-month value in the month slot); typo'd month numbers in timer definitions.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Hour values must be between 0 and 23
• Day of month values must be between 1 and 31
• '#' option is not valid here. (pos=
• Unexpected character '<c>' after '/'
• Minute and Second values must be between 0 and 59

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/cac788a1b30260e5. Report an issue: GitHub.