What causes "PARSE_TO_CRON_EXPRESSION_ERROR: parse to cron expression error" in apache/dolphinscheduler?

Fix the crontab to valid Quartz syntax: 6-7 fields, e.g. '0 0 12 * * ?' (seconds minutes hours dayOfMonth month dayOfWeek [year]).

apache/dolphinscheduler · error · ServiceException

PARSE_TO_CRON_EXPRESSION_ERROR

PARSE_TO_CRON_EXPRESSION_ERROR

Error message

PARSE_TO_CRON_EXPRESSION_ERROR: parse to cron expression error

What it means

previewSchedule could not parse the provided crontab string into a valid Quartz Cron expression via CronUtils.parse2Cron. The crontab string in the ScheduleParam is malformed or uses an unsupported cron syntax. The API rejects it so callers get a structured status instead of a raw CronParseException.

Source

Thrown at dolphinscheduler-api/src/main/java/org/apache/dolphinscheduler/api/service/impl/SchedulerServiceImpl.java:393

     * @return the next five fire time
     */
    @Override
    public List<String> previewSchedule(User loginUser, String schedule) {
        Cron cron;
        ScheduleParam scheduleParam = JSONUtils.parseObject(schedule, ScheduleParam.class);

        assert scheduleParam != null;
        ZoneId zoneId = TimeZone.getTimeZone(scheduleParam.getTimezoneId()).toZoneId();
        ZonedDateTime now = ZonedDateTime.now(zoneId);
        ZonedDateTime startTime = ZonedDateTime.ofInstant(scheduleParam.getStartTime().toInstant(), zoneId);
        ZonedDateTime endTime = ZonedDateTime.ofInstant(scheduleParam.getEndTime().toInstant(), zoneId);
        startTime = now.isAfter(startTime) ? now : startTime;

        try {
            cron = CronUtils.parse2Cron(scheduleParam.getCrontab());
        } catch (CronParseException e) {
            log.error("Parse cron to cron expression error, crontab:{}.", scheduleParam.getCrontab(), e);
            throw new ServiceException(Status.PARSE_TO_CRON_EXPRESSION_ERROR);
        }
        List<ZonedDateTime> selfFireDateList =
                CronUtils.getSelfFireDateList(startTime, endTime, cron, Constants.PREVIEW_SCHEDULE_EXECUTE_COUNT);
        return selfFireDateList.stream()
                .map(t -> DateUtils.dateToString(t, zoneId))
                .collect(Collectors.toList());
    }

    /**
     * update workflow definition schedule
     *
     * @param loginUser               login user
     * @param projectCode             project code
     * @param workflowDefinitionCode   workflow definition code
     * @param scheduleExpression      scheduleExpression
     * @param warningType             warning type
     * @param warningGroupId          warning group id
     * @param failureStrategy         failure strategy

View on GitHub (pinned to 02eac45a1b)

Solutions

Fix the crontab to valid Quartz syntax: 6-7 fields, e.g. '0 0 12 * * ?' (seconds minutes hours dayOfMonth month dayOfWeek [year]).
Use '?' instead of '*' in dayOfMonth or dayOfWeek when the other is specified.
Validate locally with CronUtils.isValidExpression(crontab) or an online Quartz cron validator before calling the preview API.
If migrating from Unix cron, convert 5-field expressions to Quartz format first.

Example fix

// before
ScheduleParam p = new ScheduleParam();
p.setCrontab("0 12 * *");            // 5 fields, invalid for Quartz

// after
p.setCrontab("0 0 12 * * ?");        // valid Quartz expression

Defensive patterns

Strategy: validation

Validate before calling

if (!CronUtils.isValidExpression(scheduleParam.getCrontab())) {
    throw new IllegalArgumentException("Invalid Quartz crontab: " + scheduleParam.getCrontab());
}

Try / catch

try {
    schedulerService.previewSchedule(loginUser, projectCode, scheduleParam, precision);
} catch (ServiceException e) {
    if (e.getCode() == Status.PARSE_TO_CRON_EXPRESSION_ERROR.getCode()) {
        // surface a field-level message for crontab
    }
}

Prevention

Always validate crontab with CronUtils.isValidExpression before API calls
Remember Quartz requires 6-7 fields (seconds first)
Use '?' for dayOfMonth/dayOfWeek mutual exclusion
Build cron strings via a cron-builder library rather than string concatenation

When it happens

Trigger: Calling the schedule preview API (previewSchedule) with a `crontab` field that fails Quartz cron parsing: wrong field count, invalid characters, out-of-range values, or non-standard syntax (e.g. @daily, 5-character POSIX crons).

Common situations: Users pasting Linux/Unix crontab syntax into DolphinScheduler, typos like '0 0 * *' (missing field), seconds field forgotten (Quartz needs 6-7 fields like '0 0 12 * * ?'), or frontend submitting an empty crontab.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/7c0108d72c788a2a. Report an issue: GitHub.