{"record":{"id":"87611ce3ed9c7718","repo":"alibaba/spring-ai-alibaba","slug":"sequential-flow-requires-at-least-one-sub-agent","errorCode":null,"errorMessage":"Sequential flow requires at least one sub-agent","messagePattern":"Sequential flow requires at least one sub-agent","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/SequentialGraphBuildingStrategy.java","lineNumber":102,"sourceCode":"\t@Override\n\tpublic String getStrategyType() {\n\t\treturn FlowAgentEnum.SEQUENTIAL.getType();\n\t}\n\n\t@Override\n\tpublic void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tsuper.validateConfig(config);\n\t\tvalidateSequentialConfig(config);\n\t}\n\n\t/**\n\t * Validates sequential-specific configuration requirements.\n\t * @param config the configuration to validate\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tprivate void validateSequentialConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Sequential flow requires at least one sub-agent\");\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(\"Sequential flow requires root agent to be a FlowAgent\");\n\t\t}\n\t}\n\n}\n","sourceCodeStart":84,"sourceCodeEnd":112,"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/SequentialGraphBuildingStrategy.java#L84-L112","documentation":"Configuration validation failure in SequentialGraphBuildingStrategy.validateSequentialConfig. A sequential flow graph is defined by chaining its sub-agents in order; if FlowGraphConfig.getSubAgents() is null or empty there is nothing to chain, so building the graph would be meaningless and IllegalArgumentException is thrown during validation (invoked from validateConfig before buildCoreGraph). Callers must add at least one sub-agent to the flow config before building a sequential agent.","triggerScenarios":"Building a SequentialAgent/sequential flow graph without registering any sub-agents before buildCoreGraph/validateConfig.","commonSituations":"Forgot .subAgents(...) on the builder; loop that appends agents never executed; agents list cleared by earlier code.","solutions":["Add at least one sub-agent via .subAgents(...)","Verify the code path that populates the agent list runs before build()","Guard with a check that subAgents is non-empty before building"],"exampleFix":"// before\nSequentialAgent.builder().name(\"flow\").build();\n// after\nSequentialAgent.builder().name(\"flow\").subAgents(step1, step2).build();","handlingStrategy":"validation","validationCode":"if (subAgents == null || subAgents.isEmpty()) {\n    throw new IllegalArgumentException(\"Sequential flow requires at least one sub-agent\");\n}","typeGuard":"static boolean hasSteps(List<? extends Agent> l) { return l != null && !l.isEmpty(); }","tryCatchPattern":null,"preventionTips":["Always register steps via .subAgents(...) before build()","Check loops/population logic that could leave the list empty","Assert non-empty step list in unit tests"],"tags":["java","agent-framework","sequential","validation"],"backgroundTag":"empty-required-field","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"}