apache/dolphinscheduler · error · IllegalArgumentException

Cannot format the date

Error message

Cannot format the date

What it means

formatTimeExpression in TimePlaceholderUtils throws this IllegalArgumentException when the time placeholder expression string is empty (null or "") and ignoreInvalidExpression is false. The date itself was valid, but there is no expression to format, so the utility refuses to guess and fails fast. Passing ignoreInvalidExpression=true makes it silently return the original (empty) expression instead of throwing.

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-api/src/main/java/org/apache/dolphinscheduler/plugin/task/api/parser/TimePlaceholderUtils.java:279

    }

    /**
     * Format time expression with given date, the date cannot be null.
     * <p> If the expression is not a time expression, return the original expression.
     *
     */
    public static String formatTimeExpression(final String timeExpression, final Date date,
                                              final boolean ignoreInvalidExpression) {
        // After N years: $[add_months(yyyyMMdd,12*N)], the first N months: $[add_months(yyyyMMdd,-N)], etc
        if (date == null) {
            throw new IllegalArgumentException("Cannot parse the expression: " + timeExpression + ", date is null");
        }
        if (StringUtils.isEmpty(timeExpression)) {
            if (ignoreInvalidExpression) {
                return timeExpression;
            }
            throw new IllegalArgumentException("Cannot format the date" + date + " with null timeExpression");
        }
        try {
            if (timeExpression.startsWith(TIMESTAMP)) {
                return calculateTimeStamp(timeExpression, date);
            }
            if (timeExpression.startsWith(YEAR_WEEK)) {
                return calculateYearWeek(timeExpression, date);
            }
            return calcTimeExpression(timeExpression, date);
        } catch (Exception e) {
            if (ignoreInvalidExpression) {
                return timeExpression;
            }
            throw new IllegalArgumentException("Unsupported placeholder expression: " + timeExpression, e);
        }
    }

    /**

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Fix the source of the empty expression: ensure the parameter value (e.g. $[yyyyMMdd], $[add_months(yyyyMMdd,-1)]) is actually populated before calling formatTimeExpression
2. Call formatTimeExpression with ignoreInvalidExpression=true if an empty expression is acceptable and should pass through unchanged
3. Guard the call site: skip formatting when the expression is null or empty
4. Check the task definition JSON for blank parameter values

Example fix

// before
String result = TimePlaceholderUtils.formatTimeExpression(expression, scheduleDate, false);
// after
String result = StringUtils.isEmpty(expression)
    ? expression
    : TimePlaceholderUtils.formatTimeExpression(expression, scheduleDate, false);

if (date == null) throw new IllegalArgumentException("date must not be null");
if (expression == null || expression.isEmpty()) {
    // skip formatting entirely or pass ignoreInvalidExpression=true
    return expression;
}
String result = TimePlaceholderUtils.formatTimeExpression(expression, date, false);

boolean isValidTimeExpression(String expr) {
    return expr != null && !expr.trim().isEmpty();
}

try {
    return TimePlaceholderUtils.formatTimeExpression(expr, date, false);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("null timeExpression")) {
        log.warn("Empty time expression, skipping formatting");
        return expr;
    }
    throw e;
}

When it happens

Trigger: Calling TimePlaceholderUtils.formatTimeExpression(date=non-null, ignoreInvalidExpression=false) with a null or empty timeExpression string. This happens when a task parameter like $[yyyyMMdd] was never filled in — e.g. an empty custom parameter value or a placeholder resolved to "" before being passed to formatTimeExpression.

Common situations: Users leave a time-placeholder parameter blank in the DolphinScheduler UI; upstream substitution produces an empty string; code paths that always call formatTimeExpression even when the expression is optional, without setting ignoreInvalidExpression=true.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Unsupported placeholder expression:
• data: %s should be a validate data string - yyyy-MM-dd HH:mm
• The date must not be null
• expression not valid
• 10158

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