kestra-io/kestra · error · PebbleException

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

Error message

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

What it means

Thrown by the 'hourOfDay()' function when the 'date' argument is null (args.get("date") returns null). hourOfDay extracts the hour (0-23) from an ISO 8601 datetime; a missing date cannot be parsed, so it is rejected up front. Note the function reads args.get rather than checking containsKey, so a present-but-null value also triggers this.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/HourOfDayFunction.java:37

 * (e.g. {@code "2025-01-06T14:30:00Z"} or {@code "2025-01-06T14:30:00+02:00"} or
 * {@code "2025-01-06T14:30:00"}). The hour is taken from the local time component as written
 * in the string; no UTC normalization is performed. Plain date strings without a time
 * component are not supported.
 *
 * <p>
 * Usage: {@code {{ hourOfDay(date) }}}
 *
 * @param date ISO 8601 datetime string (with or without timezone offset)
 */
public class HourOfDayFunction implements KestraFunction {
    public static final String NAME = "hourOfDay";

    @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 'hourOfDay()' function expects a 'date' argument.", lineNumber, self.getName());
        }

        String dateStr = dateArg.toString();

        try {
            return ZonedDateTime.parse(dateStr).getHour();
        } catch (DateTimeParseException e1) {
            try {
                return LocalDateTime.parse(dateStr).getHour();
            } catch (DateTimeParseException e2) {
                throw new PebbleException(e2, "The 'hourOfDay()' function could not parse 'date': " + e2.getMessage(), lineNumber, self.getName());
            }
        }
    }

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

View on GitHub (pinned to 823fada927)

Solutions

1. Provide a concrete ISO 8601 datetime string: hourOfDay('2026-08-14T15:30:00Z').
2. If the date comes from a variable, ensure that variable is non-null before the call, or guard it with a default.
3. Use an expression that yields a fallback, e.g. hourOfDay(inputs.date ?? execution.startDate).

Example fix

# before - missing/optional input resolves to null
h: "{{ hourOfDay(inputs.maybe_date) }}"
# after - supply a default
h: "{{ hourOfDay(inputs.maybe_date ?? execution.startDate) }}"

# Ensure 'date' is non-null before calling hourOfDay().
# {{ (dateValue != null) ? hourOfDay(dateValue) : null }}

When it happens

Trigger: Calling hourOfDay() with no arguments; passing hourOfDay(inputs.missing) where the input resolves to null; passing an expression that evaluated to null.

Common situations: Binding 'date' to an optional input that was not provided; referencing a field that does not exist on an output/object; forgetting the argument entirely.

Related errors

• The 'hourOfDay()' function could not parse 'date': {e2.getMe
• The 'encrypt' function expects two arguments 'key' and 'plai
• The 'env' function expects an argument 'name'.
• The 'fromIon' function expects an argument 'ion'.
• The 'fromJson' function expects an argument 'json'.

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