kestra-io/kestra · error · PebbleException

The 'monthOfYear()' function expects a 'date' argument.

Error message

The 'monthOfYear()' function expects a 'date' argument.

What it means

The monthOfYear(date) Pebble function requires a 'date' argument. If the args map does not contain 'date' or its value is null, the function throws before any parsing occurs. This is a contract violation indicating the function was called without its required input.

Source

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

import io.pebbletemplates.pebble.template.PebbleTemplate;

/**
 * Pebble function that returns the month of the year (1–12) of the given date.
 *
 * <p>
 * Usage: {@code {{ monthOfYear(date) }}}
 *
 * @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

View on GitHub (pinned to 823fada927)

Solutions

1. Supply a non-null date argument: {{ monthOfYear('2024-06-15') }} or {{ monthOfYear(myDateVar) }} where myDateVar is guaranteed non-null.
2. Guard against null: {% if myDateVar is not null %}{{ monthOfYear(myDateVar) }}{% endif %}.

Example fix

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

# Guard against null before calling monthOfYear:
{% if myDateVar is not null %}
  {{ monthOfYear(myDateVar) }}
{% else %}
  {{ throw('monthOfYear requires a non-null date') }}
{% endif %}

When it happens

Trigger: Calling {{ monthOfYear() }} with no arguments. Passing a variable that resolves to null. Using a named parameter that does not match 'date'.

Common situations: The flow author omits the date argument expecting a default (there is none). An upstream variable used as the date is null because the producing task has not run or produced no output.

Related errors

• The 'isWeekend()' function expects a 'date' argument.
• The 'kv' function expects an argument 'key'.
• The 'loopOutputs' function expects a non-null argument 'outp
• The 'loopOutputs' function expects a non-null argument 'name
• The 'monthOfYear()' function could not parse 'date': %s

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