apache/dolphinscheduler · error · IllegalArgumentException

Unsupported placeholder expression:

Error message

Unsupported placeholder expression: 

What it means

The catch-all in formatTimeExpression: any exception raised while evaluating a placeholder (bad syntax, unknown function, arithmetic errors from nested calculate(), or the RuntimeExceptions from calculateYearWeek/calcMonthBegin) is rethrown as IllegalArgumentException("Unsupported placeholder expression: ...", e) when ignoreInvalidExpression is false. The expression was non-empty but does not match any supported time-placeholder grammar, or is malformed for the matched branch.

Source

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

        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);
        }
    }

    /**
     * get week of year
     * @param expression expression
     * @param date       date
     * @return week of year
     */
    private static String calculateYearWeek(final String expression, final Date date) {

        String dataFormat = expression.substring(YEAR_WEEK.length() + 1, expression.length() - 1);

        String targetDate = "";
        try {

            if (dataFormat.contains(COMMA)) {
                String param1 = dataFormat.split(COMMA)[0];

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Verify the expression syntax against supported forms, e.g. $[yyyyMMdd], $[add_months(yyyyMMdd,-N)], $[month_begin(yyyyMMdd,N)], $[week_begin(yyyyMMdd,N)], $N, $Y
2. Inspect the cause chain (getCause) — the IllegalArgumentException wraps the real error (e.g. 'expression not valid', NumberFormatException)
3. Call with ignoreInvalidExpression=true to have invalid expressions returned unchanged instead of failing the task
4. Print/log the exact timeExpression string and test it in a unit test against TimePlaceholderUtils

Example fix

// before
String result = TimePlaceholderUtils.formatTimeExpression("$[add_months(yyyyMMdd,-1x)]", date, false);
// throws: Unsupported placeholder expression: $[add_months(yyyyMMdd,-1x)]
// after
String result = TimePlaceholderUtils.formatTimeExpression("$[add_months(yyyyMMdd,-1)]", date, false);

// Pre-check the expression against known prefixes and balanced parens
boolean isPlausible(String e) {
    if (e == null || e.isEmpty()) return false;
    long opens = e.chars().filter(c -> c == '(').count();
    long closes = e.chars().filter(c -> c == ')').count();
    return opens == closes;
}

try {
    return TimePlaceholderUtils.formatTimeExpression(expr, date, false);
} catch (IllegalArgumentException e) {
    Throwable cause = e.getCause();
    log.error("Unsupported time placeholder '{}': {}", expr, cause == null ? e.getMessage() : cause.getMessage());
    throw new TaskException("Invalid time placeholder in task params: " + expr, e);
}

When it happens

Trigger: formatTimeExpression(timeExpression, date, false) where timeExpression starts with $N, $Y, $M or similar but the inner expression is syntactically invalid (e.g. missing closing paren, non-numeric offset like $[yyyyMMdd+abc], a month-begin expression without exactly two comma-separated params, or a $[week(yyyymmww)] with a bad format). Any exception from calcTimeExpression / calculateYearWeek / calculateTimeStamp lands here.

Common situations: Typos in scheduler parameter expressions ($[add_months(yyMMdd,-1)] — wrong format token), missing parenthesis, arithmetic operators on non-numeric values, expressions copied from docs of a different scheduler version where the grammar changed.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Cannot format the date
• expression not valid
• data: %s should be a validate data string - yyyy-MM-dd HH:mm
• The date must not be null
• remote.logging.google.cloud.storage.bucket.name is blank

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