{"record":{"id":"a89ca84938c87215","repo":"alibaba/spring-ai-alibaba","slug":"maxconcurrency-must-be-at-least-1-but-got","errorCode":null,"errorMessage":"maxConcurrency must be at least 1, but got: ","messagePattern":"maxConcurrency must be at least 1, but got: ","errorType":"exception","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":267,"sourceCode":"\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\n\t\t\t// result merging\n\t\t\tvalidateUniqueOutputKeys();\n\n\t\t\t// Validate input key compatibility\n\t\t\tvalidateInputKeyCompatibility();\n\n\t\t\t// Validate concurrency limit - allow maxConcurrency to be null (unlimited) or\n\t\t\t// within valid range\n\t\t\tif (maxConcurrency != null) {\n\t\t\t\tif (maxConcurrency < 1) {\n\t\t\t\t\tthrow new IllegalArgumentException(\"maxConcurrency must be at least 1, but got: \" + maxConcurrency);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t/**\n\t\t * Validates that all sub-agents have unique output keys.\n\t\t */\n\t\tprivate void validateUniqueOutputKeys() {\n\t\t\tSet<String> outputKeys = new HashSet<>();\n\t\t\tSet<String> duplicateKeys = new HashSet<>();\n\n\t\t\tfor (Agent subAgent : subAgents) {\n\t\t\t\tif (subAgent instanceof ReactAgent subReactAgent) {\n\t\t\t\t\tString outputKey = subReactAgent.getOutputKey();\n\t\t\t\t\tif (outputKey != null) {\n\t\t\t\t\t\tif (!outputKeys.add(outputKey)) {\n\t\t\t\t\t\t\t// This key was already seen, it's a duplicate\n\t\t\t\t\t\t\tduplicateKeys.add(outputKey);","sourceCodeStart":249,"sourceCodeEnd":285,"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#L249-L285","documentation":"If maxConcurrency is set on a ParallelAgent builder, it must be >= 1; validate() rejects null-like misuse and any value below 1 (0, negative). maxConcurrency limits how many sub-agents run concurrently; only null (unlimited) or a positive value is accepted.","triggerScenarios":"ParallelAgent.builder()...maxConcurrency(0).build() or maxConcurrency(-1), typically when maxConcurrency is computed from config or a ratio that evaluated to 0.","commonSituations":"Reading a concurrency limit from properties where the key is missing and defaults to 0; computing concurrency from a percentage that rounds down to 0.","solutions":["Pass a positive integer, e.g. maxConcurrency(2)","Fix the config/source so it yields >= 1, clamping: Math.max(1, value)","Omit maxConcurrency entirely (null) for unlimited concurrency"],"exampleFix":"// before\nint concurrency = Integer.parseInt(props.getProperty(\"fanout.concurrency\", \"0\"));\nbuilder.maxConcurrency(concurrency);\n// after\nbuilder.maxConcurrency(Math.max(1, Integer.parseInt(props.getProperty(\"fanout.concurrency\", \"1\"))));","handlingStrategy":"validation","validationCode":"int c = parseConcurrency(cfg); if (c < 1) c = 1; builder.maxConcurrency(c);","typeGuard":"Integer safeConcurrency(Integer c) { return (c == null || c < 1) ? null : c; }","tryCatchPattern":"try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"maxConcurrency must be at least 1\")) { /* clamp and rebuild */ } else throw e; }","preventionTips":["Clamp config-derived concurrency with Math.max(1, v)","Use null for unlimited instead of 0","Validate concurrency keys in config at startup"],"tags":["validation","concurrency","config"],"backgroundTag":"invalid-config-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"}