kestra-io/kestra · error · PebbleException

Failed to run subflow '%s'.'%s': %s

Error message

Failed to run subflow '%s'.'%s': %s

What it means

After successfully creating the execution with valid inputs, the subflow() function calls executionService.runAndWait() which starts the execution and blocks until it reaches a terminal state (or times out). If runAndWait itself throws an exception (infrastructure failure, timeout, queue error, internal error), the function wraps it as a PebbleException with the original message. This is distinct from error 217 (which fires when the subflow completes normally but in a non-success state).

Source

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

            }

            Execution execution;
            try {
                execution = Execution.newExecution(
                    targetFlow,
                    (f, e) -> flowInputOutput.get().readExecutionInputs(f, e, inputs),
                    labels,
                    Optional.empty()
                );
            } catch (Exception e) {
                throw new PebbleException(e, "Invalid inputs for subflow '" + namespace + "'.'" + id + "': " + e.getMessage(), lineNumber, self.getName());
            }

            Execution terminated;
            try {
                terminated = executionService.get().runAndWait(execution, targetFlow, timeout);
            } catch (Exception e) {
                throw new PebbleException(e, "Failed to run subflow '" + namespace + "'.'" + id + "': " + e.getMessage(), lineNumber, self.getName());
            }

            State.Type state = terminated.getState().getCurrent();
            if (state != State.Type.SUCCESS && state != State.Type.WARNING) {
                throw new PebbleException(
                    null, "Subflow '" + namespace + "'.'" + id + "' ended in state " + state
                        + " (execution " + terminated.getId() + ").",
                    lineNumber, self.getName()
                );
            }

            return Result.of(terminated);
        } finally {
            int current = DEPTH.get() - 1;
            if (current <= 0) {
                DEPTH.remove();
            } else {
                DEPTH.set(current);

View on GitHub (pinned to 823fada927)

Solutions

1. If the error is timeout-related, increase the 'timeout' argument: subflow(..., timeout='PT5M') for 5 minutes.
2. Check Kestra server logs for the underlying infrastructure error.
3. Verify the executor, database, and queue are healthy and not under excessive load.
4. If the target flow is inherently long-running, consider using the Subflow task type with wait=true instead of the blocking subflow() function.

Example fix

# before — default timeout too short for a 3-minute flow
{{ subflow(namespace='company.team', id='slow_flow') }}

# after — explicit timeout that accommodates the flow runtime
{{ subflow(namespace='company.team', id='slow_flow', timeout='PT5M') }}

# If the error is timeout-related, provide an explicit timeout argument:
# {{ subflow(namespace='ns', id='child', timeout='PT5M') }}
# Before calling, verify Kestra infrastructure health:
#   - Check executor, queue, and database are running
#   - Review server logs for the underlying exception
# For long-running child flows, prefer the Subflow task type over subflow().

When it happens

Trigger: The Kestra executor or queue experiences an internal error while starting or running the child execution. The timeout configured for subflow() (via the 'timeout' argument or SubflowFunctionConfiguration.defaultTimeout) is exceeded. The execution system is under heavy load and runAndWait fails to complete. A database or storage backend error occurs during execution.

Common situations: The subflow() timeout is too short for the target flow's actual runtime. Infrastructure issues (database down, queue full, executor overwhelmed). Network partition between Kestra services. The default timeout is hit because the child flow is long-running.

Related errors

• The 'subflow' function 'timeout' must be an ISO-8601 duratio
• The 'subflow' function 'timeout' must be an ISO-8601 duratio
• The 'subflow' function 'timeout' (%s) exceeds the maximum al
• The 'subflow' function can only be used at flow-input render
• The 'subflow' function expects the arguments 'namespace' and

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