{"record":{"id":"671c49d43fe258f2","repo":"alibaba/spring-ai-alibaba","slug":"name-must-be-provided-671c49","errorCode":null,"errorMessage":"Name must be provided","messagePattern":"Name must be provided","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/ParallelAgent.java","lineNumber":238,"sourceCode":"\n\t\t/**\n\t\t * Returns the concrete builder instance for fluent interface support.\n\t\t * @return this builder instance\n\t\t */\n\t\t@Override\n\t\tprotected ParallelAgentBuilder self() {\n\t\t\treturn this;\n\t\t}\n\n\t\t/**\n\t\t * Validates the builder state before creating the agent.\n\t\t * @throws IllegalArgumentException if validation fails\n\t\t */\n\t\t@Override\n\t\tprotected void validate() {\n\t\t\t// Validate name first (from parent)\n\t\t\tif (name == null || name.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"Name must be provided\");\n\t\t\t}\n\n\t\t\t// Validate minimum sub-agent count for ParallelAgent (skip parent subAgents\n\t\t\t// check)\n\t\t\tif (subAgents == null || subAgents.size() < 2) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\t\"ParallelAgent requires at least 2 sub-agents for parallel execution, but got: \"\n\t\t\t\t\t\t\t\t+ (subAgents != null ? subAgents.size() : 0));\n\t\t\t}\n\n\t\t\t// Validate maximum sub-agent count for performance reasons\n\t\t\tif (subAgents.size() > 10) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\t\"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: \"\n\t\t\t\t\t\t\t\t+ subAgents.size());\n\t\t\t}\n\n\t\t\t// Validate that sub-agents have unique output keys to avoid conflicts during","sourceCodeStart":220,"sourceCodeEnd":256,"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/agent/ParallelAgent.java#L220-L256","documentation":"ParallelAgent.Builder.validate() throws this before building when the agent name is null or blank. Every flow agent must have a name, since it is used as the node identifier in the compiled graph. This is a fail-fast guard in the builder phase, not a runtime condition.","triggerScenarios":"Calling ParallelAgent.builder() ... .build() without calling .name(\"...\") first, or passing a name of only whitespace (e.g. .name(\"   \")).","commonSituations":"Programmatic agent construction where the name comes from a nullable config property or is accidentally set after build(); copy-pasting a builder and forgetting the name line.","solutions":["Call .name(\"<unique-agent-name>\") on the builder before .build()","Ensure the value source (config/env) actually supplies a non-blank name","If the name is dynamic, trim and check it before invoking the builder"],"exampleFix":"// before\nParallelAgent.builder().subAgents(a, b).build();\n// after\nParallelAgent.builder().name(\"parallel-worker\").subAgents(a, b).build();","handlingStrategy":"validation","validationCode":"if (name == null || name.trim().isEmpty()) throw new IllegalArgumentException(\"Agent name required before build()\");","typeGuard":"boolean hasName(String s) { return s != null && !s.isBlank(); }","tryCatchPattern":"try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"Name must be provided\")) { /* set name and rebuild */ } else throw e; }","preventionTips":["Always make .name(...) the first builder call","Extract agent names into named constants or config with non-blank defaults","Add a unit test that builds every agent in the app"],"tags":["validation","builder","missing-name"],"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"}