kestra-io/kestra · error · PebbleException

The 'subflow' function 'timeout' (%s) exceeds the maximum al

Error message

The 'subflow' function 'timeout' (%s) exceeds the maximum allowed (%s).

What it means

The `subflow()` function enforces a maximum timeout via `SubflowFunctionConfiguration.maxTimeout()`. After parsing the timeout value, if the resolved `Duration` exceeds this configured ceiling, the function throws a `PebbleException`. This prevents a synchronous blocking call from holding a webserver IO thread indefinitely.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/SubflowFunction.java:252

    private Duration resolveTimeout(Object rawTimeout, PebbleTemplate self, int lineNumber) {
        Duration timeout;
        if (rawTimeout == null) {
            timeout = configuration.defaultTimeout();
        } else if (rawTimeout instanceof Duration d) {
            timeout = d;
        } else if (rawTimeout instanceof String s) {
            try {
                timeout = Duration.parse(s);
            } catch (DateTimeParseException e) {
                throw new PebbleException(e, "The 'subflow' function 'timeout' must be an ISO-8601 duration (e.g. 'PT30S'), got '" + s + "'.", lineNumber, self.getName());
            }
        } else {
            throw new PebbleException(null, "The 'subflow' function 'timeout' must be an ISO-8601 duration string (e.g. 'PT30S').", lineNumber, self.getName());
        }

        if (timeout.compareTo(configuration.maxTimeout()) > 0) {
            throw new PebbleException(null, "The 'subflow' function 'timeout' (" + timeout + ") exceeds the maximum allowed (" + configuration.maxTimeout() + ").", lineNumber, self.getName());
        }
        return timeout;
    }

    /**
     * The minimal, navigable result returned to the template, instead of the full {@link Execution}
     * object (which exposes internal state callers should not depend on).
     *
     * @param id the terminal execution id
     * @param state the terminal state name (e.g. {@code SUCCESS})
     * @param outputs the subflow's flow-level outputs, navigable as {@code subflow(...).outputs.xxx}
     * @param labels the execution labels as a {@code key -> value} map
     */
    public record Result(String id, String state, Map<String, Object> outputs, Map<String, String> labels) {
        static Result of(Execution execution) {
            Map<String, String> labels = new HashMap<>();
            execution.getLabels().forEach(label -> labels.put(label.key(), label.value()));

View on GitHub (pinned to 823fada927)

Solutions

1. Reduce the `timeout` argument to a value within the configured maximum.
2. Increase `kestra.plugins.subflow.max-timeout` in the server configuration (requires admin access and a restart).
3. Redesign the subflow to complete faster, or switch to an asynchronous Subflow task instead of the synchronous `subflow()` function.

Example fix

# before
values: "{{ subflow(namespace='company.team', id='slow_flow', timeout='PT2H') }}"
# after
values: "{{ subflow(namespace='company.team', id='slow_flow', timeout='PT10M') }}"

// Check against configured max before calling
import java.time.Duration;

Duration maxTimeout = configuration.maxTimeout(); // e.g. PT10M
Duration requested = Duration.parse("PT2H");
if (requested.compareTo(maxTimeout) > 0) {
    throw new IllegalArgumentException("Requested timeout exceeds max: " + maxTimeout);
}

When it happens

Trigger: Passing `timeout='PT24H'` when `kestra.plugins.subflow.max-timeout` is set to `PT10M` (the effective default or admin-configured value). Any duration that exceeds the server-side ceiling.

Common situations: A subflow legitimately takes a long time to complete, but the admin has capped the maximum timeout. A developer copies a large timeout value from another context without checking the configured ceiling.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Failed to run subflow '%s'.'%s': %s
• The 'subflow' function 'timeout' must be an ISO-8601 duratio
• The 'subflow' function 'timeout' must be an ISO-8601 duratio
• The file:// protocol has been disabled inside the Kestra con
• Maximum render() nesting depth (%s) exceeded at line %s — ch

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