kestra-io/kestra · error · PebbleException

The 'monthOfYear()' function could not parse 'date': %s

Error message

The 'monthOfYear()' function could not parse 'date': %s

What it means

The monthOfYear(date) function calls DateUtils.parseLocalDate, which attempts LocalDate.parse, then ZonedDateTime.parse, then LocalDateTime.parse — all expecting ISO 8601. If all three fail, the InternalException is wrapped in this PebbleException with the original DateTimeException message appended.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/MonthOfYearFunction.java:38

 *
 * @param date any valid ISO 8601 date or datetime string
 */
public class MonthOfYearFunction implements KestraFunction {
    public static final String NAME = "monthOfYear";

    @Override
    public Object execute(Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
        Object dateArg = args.get("date");

        if (dateArg == null) {
            throw new PebbleException(null, "The 'monthOfYear()' function expects a 'date' argument.", lineNumber, self.getName());
        }

        LocalDate localDate;
        try {
            localDate = DateUtils.parseLocalDate(dateArg.toString());
        } catch (InternalException e) {
            throw new PebbleException(e, "The 'monthOfYear()' function could not parse 'date': " + e.getMessage(), lineNumber, self.getName());
        }

        return localDate.getMonthValue();
    }

    @Override
    public List<String> getArgumentNames() {
        return List.of("date");
    }

    @Override
    // HashMap is required here because Map.of() does not allow null values,
    // and null defaults indicate arguments with no meaningful autocompletion default.
    public Map<String, String> getArgumentDefaults() {
        HashMap<String, String> defaults = new HashMap<>();
        defaults.put("date", null);
        return defaults;
    }

View on GitHub (pinned to 823fada927)

Solutions

1. Convert the date to ISO 8601 format (yyyy-MM-dd) before calling monthOfYear.
2. Check the appended e.getMessage() for the exact parse failure detail.
3. Use an intermediate task or expression to reformat the date if it comes from an external source.

Example fix

# before
value: "{{ monthOfYear('15/06/2024') }}"
# after
value: "{{ monthOfYear('2024-06-15') }}"

# Validate ISO 8601 format before calling monthOfYear:
{% set datePattern = /^\d{4}-\d{2}-\d{2}(T.*)?$/ %}
{% if myDateVar matches datePattern %}
  {{ monthOfYear(myDateVar) }}
{% else %}
  {{ throw('date must be ISO 8601') }}
{% endif %}

When it happens

Trigger: Passing '06/15/2024', '15.06.2024', 'June 15 2024', epoch timestamps, or any non-ISO 8601 string.

Common situations: An upstream task or external API provides dates in regional or custom formats. The user assumes natural-language date parsing is supported.

Related errors

• The 'isPublicHoliday()' function could not parse 'date': {e.
• The 'isWeekend()' function could not parse 'date': {e.getMes
• The 'monthOfYear()' function expects a 'date' argument.
• The 'isWeekend()' function expects a 'date' argument.
• {e.getMessage()}

AI-assisted analysis of kestra-io/kestra@823fada927 (2026-08-14). Data as JSON: /api/errors/687f96ddf3585a97. Report an issue: GitHub.