kestra-io/kestra · error · PebbleException

Cannot run the invalid flow '%s'.'%s': %s

Error message

Cannot run the invalid flow '%s'.'%s': %s

What it means

After resolving the target flow by namespace/id/revision, the subflow() function checks whether the returned FlowWithSource is actually a FlowWithException — meaning the flow exists but failed validation and is marked as invalid (it has a stored exception message). In this state the flow cannot be executed, and the function surfaces the original validation exception so the user knows what is wrong with the target flow.

Source

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

        DEPTH.set(depth + 1);
        try {
            // ACL is scoped to the caller flow (callerNamespace/callerId), matching the Subflow task trust model:
            // if the caller flow may reference the target, so may subflow(). Note this is reachable at execute-form
            // render time, not only at execution time, so anyone able to open the form triggers this resolution.
            // resolved for runtime so a governance rejection surfaces as a FlowWithException here, rather than
            // becoming a created-then-failed execution
            FlowWithSource targetFlow = flowMetaStore.get()
                .findByIdFromTaskForRuntime(tenantId, namespace, id, revision, tenantId, callerNamespace, callerId)
                .orElseThrow(
                    () -> new PebbleException(
                        null, "Unable to find flow '" + namespace + "'.'" + id + "'"
                            + revision.map(r -> " with revision " + r).orElse("") + ".",
                        lineNumber, self.getName()
                    )
                );

            if (targetFlow instanceof FlowWithException fwe) {
                throw new PebbleException(null, "Cannot run the invalid flow '" + namespace + "'.'" + id + "': " + fwe.getException(), lineNumber, self.getName());
            }
            if (targetFlow.isDisabled()) {
                throw new PebbleException(null, "Cannot run the disabled flow '" + namespace + "'.'" + id + "'.", lineNumber, self.getName());
            }

            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;

View on GitHub (pinned to 823fada927)

Solutions

1. Open the target flow in the Kestra UI and fix the validation error indicated by the exception message.
2. Ensure all plugins referenced by the target flow are installed.
3. If the target flow was deleted or renamed, update the subflow() call to reference the correct flow.
4. Validate the target flow YAML with the Kestra flow validator before deploying.

Example fix

# before — target flow 'child' is invalid (has a validation error)
{{ subflow(namespace='company.team', id='child') }}

# Fix the target flow 'child' in the UI/editor — the exception message tells you what is wrong.
# Then the subflow() call will succeed.
# No Pebble-level fix exists; the target flow itself must be corrected.

# Before calling subflow() on a target flow, verify it is valid:
# 1. Open the target flow in the Kestra UI — if it shows a validation error, fix it first.
# 2. Use the Kestra API to check the flow's status:
#    GET /api/v1/flows/{namespace}/{id} — a FlowWithException will include the exception field.
# There is no Pebble-level pre-check; the target flow must be valid by construction.

When it happens

Trigger: The target flow has a YAML syntax error, a missing required plugin, an invalid task configuration, or another validation failure that makes it unloadable as a runnable flow. Calling subflow(namespace='ns', id='broken_flow') where 'broken_flow' exists but is in an error state.

Common situations: The target flow was recently edited and has a validation error that hasn't been fixed yet. A plugin referenced by the target flow is missing from the classpath. A dependency between flows means an upstream edit broke a downstream flow used in a subflow() call.

Related errors

• The 'subflow' function can only be used at flow-input render
• The 'subflow' function expects the arguments 'namespace' and
• The 'subflow' function can only be used in a flow context (e
• The 'subflow' function exceeded the maximum nesting depth of
• Cannot run the disabled flow '%s'.'%s'.

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