{"record":{"id":"548cac102be49ee6","repo":"kestra-io/kestra","slug":"failed-to-run-subflow-s-s-s","errorCode":null,"errorMessage":"Failed to run subflow '%s'.'%s': %s","messagePattern":"Failed to run subflow '(.+?)'\\.'(.+?)': (.+?)","errorType":"exception","errorClass":"PebbleException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/io/kestra/core/runners/pebble/functions/SubflowFunction.java","lineNumber":186,"sourceCode":"            }\n\n            Execution execution;\n            try {\n                execution = Execution.newExecution(\n                    targetFlow,\n                    (f, e) -> flowInputOutput.get().readExecutionInputs(f, e, inputs),\n                    labels,\n                    Optional.empty()\n                );\n            } catch (Exception e) {\n                throw new PebbleException(e, \"Invalid inputs for subflow '\" + namespace + \"'.'\" + id + \"': \" + e.getMessage(), lineNumber, self.getName());\n            }\n\n            Execution terminated;\n            try {\n                terminated = executionService.get().runAndWait(execution, targetFlow, timeout);\n            } catch (Exception e) {\n                throw new PebbleException(e, \"Failed to run subflow '\" + namespace + \"'.'\" + id + \"': \" + e.getMessage(), lineNumber, self.getName());\n            }\n\n            State.Type state = terminated.getState().getCurrent();\n            if (state != State.Type.SUCCESS && state != State.Type.WARNING) {\n                throw new PebbleException(\n                    null, \"Subflow '\" + namespace + \"'.'\" + id + \"' ended in state \" + state\n                        + \" (execution \" + terminated.getId() + \").\",\n                    lineNumber, self.getName()\n                );\n            }\n\n            return Result.of(terminated);\n        } finally {\n            int current = DEPTH.get() - 1;\n            if (current <= 0) {\n                DEPTH.remove();\n            } else {\n                DEPTH.set(current);","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/core/src/main/java/io/kestra/core/runners/pebble/functions/SubflowFunction.java#L168-L204","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["If the error is timeout-related, increase the 'timeout' argument: subflow(..., timeout='PT5M') for 5 minutes.","Check Kestra server logs for the underlying infrastructure error.","Verify the executor, database, and queue are healthy and not under excessive load.","If the target flow is inherently long-running, consider using the Subflow task type with wait=true instead of the blocking subflow() function."],"exampleFix":"# before — default timeout too short for a 3-minute flow\n{{ subflow(namespace='company.team', id='slow_flow') }}\n\n# after — explicit timeout that accommodates the flow runtime\n{{ subflow(namespace='company.team', id='slow_flow', timeout='PT5M') }}","handlingStrategy":"retry","validationCode":"# If the error is timeout-related, provide an explicit timeout argument:\n# {{ subflow(namespace='ns', id='child', timeout='PT5M') }}\n# Before calling, verify Kestra infrastructure health:\n#   - Check executor, queue, and database are running\n#   - Review server logs for the underlying exception\n# For long-running child flows, prefer the Subflow task type over subflow().","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set an explicit timeout that comfortably exceeds the target flow's expected runtime.","Monitor Kestra executor and queue health.","For inherently long-running flows, use the Subflow task type instead of subflow().","Keep child flows lightweight when called from subflow() to stay within timeouts."],"tags":["pebble","subflow","timeout","infrastructure","execution-error"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}