apache/dolphinscheduler · error · ServiceException

REQUEST_PARAMS_NOT_VALID_ERROR

REQUEST_PARAMS_NOT_VALID_ERROR

Error message

REQUEST_PARAMS_NOT_VALID_ERROR: request parameter {crontab} is not valid

What it means

REQUEST_PARAMS_NOT_VALID_ERROR with the parameter name 'crontab' is thrown by insertSchedule when CronUtils.isValidExpression() cannot parse the supplied cron expression. DolphinScheduler uses Quartz-compatible cron syntax (6-7 fields, seconds first) and validates it before scheduling. The message interpolates the offending crontab string as the parameter.

Source

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

        scheduleObj.setProjectName(project.getName());
        scheduleObj.setWorkflowDefinitionCode(workflowDefinitionCode);
        scheduleObj.setWorkflowDefinitionName(workflowDefinition.getName());

        ScheduleParam scheduleParam = JSONUtils.parseObject(schedule, ScheduleParam.class);
        if (DateUtils.differSec(scheduleParam.getStartTime(), scheduleParam.getEndTime()) == 0) {
            log.warn("The start time must not be the same as the end or time can not be null.");
            throw new ServiceException(Status.SCHEDULE_START_TIME_END_TIME_SAME);
        }
        if (scheduleParam.getStartTime().getTime() > scheduleParam.getEndTime().getTime()) {
            log.warn("The start time must smaller than end time");
            throw new ServiceException(Status.START_TIME_BIGGER_THAN_END_TIME_ERROR);
        }

        scheduleObj.setStartTime(scheduleParam.getStartTime());
        scheduleObj.setEndTime(scheduleParam.getEndTime());
        if (!CronUtils.isValidExpression(scheduleParam.getCrontab())) {
            log.error("Schedule crontab verify failure, crontab:{}.", scheduleParam.getCrontab());
            throw new ServiceException(Status.REQUEST_PARAMS_NOT_VALID_ERROR, scheduleParam.getCrontab());
        }
        scheduleObj.setCrontab(scheduleParam.getCrontab());
        validateMissedFirePolicy(scheduleParam);
        scheduleObj.setMissedFirePolicy(scheduleParam.getMissedFirePolicy());
        scheduleObj.setTimezoneId(scheduleParam.getTimezoneId());
        scheduleObj.setWarningType(warningType);
        scheduleObj.setWarningGroupId(warningGroupId);
        scheduleObj.setFailureStrategy(failureStrategy);
        scheduleObj.setCreateTime(now);
        scheduleObj.setUpdateTime(now);
        scheduleObj.setUserId(loginUser.getId());
        scheduleObj.setUserName(loginUser.getUserName());
        scheduleObj.setReleaseState(ReleaseState.OFFLINE);
        scheduleObj.setWorkflowInstancePriority(workflowInstancePriority);
        scheduleObj.setWorkerGroup(workerGroup);
        scheduleObj.setEnvironmentCode(environmentCode);
        scheduleDao.insert(scheduleObj);

View on GitHub (pinned to 02eac45a1b)

Solutions

Rewrite the expression as a Quartz cron (format: seconds minutes hours dayOfMonth month dayOfWeek [year]), e.g. "0 0 0 * * ? *".
Use the schedule preview endpoint (POST /schedule/preview) or CronUtils to test the expression before saving.
Check field values are in range (seconds/minutes 0-59, hours 0-23, day-of-month 1-31) and that DAY fields use '?' where appropriate.

Example fix

// before
{"crontab":"0 0 * * *"}            // Unix 5-field cron
// after
{"crontab":"0 0 0 * * ? *"}         // Quartz daily at midnight

Defensive patterns

Strategy: validation

Validate before calling

// CronUtils is internal; replicate a Quartz-style check before calling:
if (!org.quartz.CronExpression.isValidExpression(param.getCrontab())) {
    throw new IllegalArgumentException("crontab is not a valid Quartz expression: " + param.getCrontab());
}

Try / catch

try { schedulerService.insertSchedule(...); } catch (ServiceException e) { if (e.getCode() == Status.REQUEST_PARAMS_NOT_VALID_ERROR) { /* log e.getMessage(); fix crontab */ } }

Prevention

Use Quartz 6-7 field cron syntax (seconds first), not 5-field Unix cron
Validate with the schedule preview endpoint before saving
Keep a library of tested cron expressions for common intervals

When it happens

Trigger: POST /projects/{projectCode}/schedule with schedule JSON containing a malformed crontab, e.g. "crontab":"0 0 * *" (missing fields) or Unix-style "0 0 * * *" without a seconds field, or an invalid field value like "0 0 32 * * ?".

Common situations: Reusing Unix crontab expressions (5 fields) in DolphinScheduler (Quartz needs seconds field plus optional year); typos such as commas in the day-of-week field; forgetting the '?' in day-of-month/day-of-week; migrating schedules from other schedulers with different cron dialects.

Related errors

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