{"record":{"id":"ce55ab762ab212c5","repo":"alibaba/spring-ai-alibaba","slug":"parallel-flow-requires-root-agent-to-be-a-flowagen","errorCode":null,"errorMessage":"Parallel flow requires root agent to be a FlowAgent","messagePattern":"Parallel flow requires root agent to be a FlowAgent","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/ParallelGraphBuildingStrategy.java","lineNumber":163,"sourceCode":"\n\t/**\n\t * Validates parallel-specific configuration requirements.\n\t * @param config the configuration to validate\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tprivate void validateParallelConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Parallel flow requires at least one sub-agent\");\n\t\t}\n\n\t\tif (config.getSubAgents().size() < 2) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Parallel flow requires at least 2 sub-agents for meaningful parallel execution\");\n\t\t}\n\n\t\t// Ensure root agent is a FlowAgent for input key access\n\t\tif (!(config.getRootAgent() instanceof FlowAgent)) {\n\t\t\tthrow new IllegalArgumentException(\"Parallel flow requires root agent to be a FlowAgent\");\n\t\t}\n\n\t\t// Validate maxConcurrency if provided\n\t\tInteger maxConcurrency = (Integer) config.getCustomProperty(\"maxConcurrency\");\n\t\tif (maxConcurrency != null && maxConcurrency < 1) {\n\t\t\tthrow new IllegalArgumentException(\"maxConcurrency must be at least 1, but got: \" + maxConcurrency);\n\t\t}\n\t}\n\n}\n","sourceCodeStart":145,"sourceCodeEnd":174,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/ParallelGraphBuildingStrategy.java#L145-L174","documentation":"ParallelGraphBuildingStrategy requires the configured root agent to be an instance of FlowAgent so it can access the input key used to fan out sub-agent execution. Throwing IllegalArgumentException when config.getRootAgent() is not a FlowAgent.","triggerScenarios":"Calling ParallelAgent/FlowGraphBuilder with a root agent that is a plain BaseAgent or custom Agent implementation rather than a FlowAgent subclass, then building the graph (buildCoreGraph or validateConfig).","commonSituations":"Passing a custom agent wrapper as the root of a parallel flow; composing flows where the root was created by a non-flow factory; refactoring that changed the root agent type.","solutions":["Make the root agent a FlowAgent subclass (e.g. ParallelAgent or another FlowAgent)","Check the agent factory/builder used to create the root and ensure it produces a FlowAgent","If a custom root is needed, extend FlowAgent so it exposes the input key"],"exampleFix":"// before\nAgent root = new MyCustomAgent(\"root\");\nParallelAgent.builder().rootAgent(root)...build();\n// after\nFlowAgent root = ParallelAgent.builder().subAgents(a, b).build();","handlingStrategy":"validation","validationCode":"if (!(config.getRootAgent() instanceof FlowAgent)) {\n    throw new IllegalStateException(\"Parallel flow root must be a FlowAgent, got: \" + config.getRootAgent().getClass().getName());\n}","typeGuard":"static boolean isValidParallelRoot(Agent a) { return a instanceof FlowAgent; }","tryCatchPattern":null,"preventionTips":["Always build parallel flows through ParallelAgent.builder() so the root is a FlowAgent","Assert root type in unit tests before building graphs","Avoid manually constructing FlowGraphConfig with arbitrary Agent roots"],"tags":["java","agent-framework","graph-building","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}