{"record":{"id":"b66661fd7b78e903","repo":"alibaba/spring-ai-alibaba","slug":"maxparalleltools-must-be-at-least-1-b66661","errorCode":null,"errorMessage":"maxParallelTools must be at least 1","messagePattern":"maxParallelTools must be at least 1","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/node/AgentToolNode.java","lineNumber":932,"sourceCode":"\t\t * execute concurrently up to {@link #maxParallelTools} limit.\n\t\t * @param parallel true to enable parallel execution\n\t\t * @return this builder\n\t\t */\n\t\tpublic Builder parallelToolExecution(boolean parallel) {\n\t\t\tthis.parallelToolExecution = parallel;\n\t\t\treturn this;\n\t\t}\n\n\t\t/**\n\t\t * Set the maximum number of tools to execute in parallel. This limits concurrent\n\t\t * tool executions to prevent resource exhaustion.\n\t\t * @param max the maximum parallel tools (default: 5)\n\t\t * @return this builder\n\t\t * @throws IllegalArgumentException if max is less than 1\n\t\t */\n\t\tpublic Builder maxParallelTools(int max) {\n\t\t\tif (max < 1) {\n\t\t\t\tthrow new IllegalArgumentException(\"maxParallelTools must be at least 1\");\n\t\t\t}\n\t\t\tthis.maxParallelTools = max;\n\t\t\treturn this;\n\t\t}\n\n\t\t/**\n\t\t * Set the timeout for each tool execution.\n\t\t * @param timeout the timeout duration (default: 5 minutes)\n\t\t * @return this builder\n\t\t */\n\t\tpublic Builder toolExecutionTimeout(Duration timeout) {\n\t\t\tthis.toolExecutionTimeout = timeout;\n\t\t\treturn this;\n\t\t}\n\n\t\t/**\n\t\t * Enable automatic wrapping of synchronous tools as async.\n\t\t *","sourceCodeStart":914,"sourceCodeEnd":950,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/node/AgentToolNode.java#L914-L950","documentation":"AgentToolNode.Builder.maxParallelTools(int) sets the concurrency limit for parallel tool execution; a value below 1 would deadlock or never run any tool, so the builder throws IllegalArgumentException when max < 1. Default is 5.","triggerScenarios":"Calling AgentToolNode.builder().maxParallelTools(0) or a negative value.","commonSituations":"maxParallelTools loaded from config where 0 or unset is the default; computing the limit from available CPUs or a quota that evaluated to 0; disabling parallelism with 0 instead of using 1 (sequential).","solutions":["Use maxParallelTools(1) to run tools sequentially","Provide a positive value, e.g. maxParallelTools(5)","Clamp/validate config before building: max = Math.max(1, configured)"],"exampleFix":"// before\nAgentToolNode.builder().maxParallelTools(0).build();\n// after\nAgentToolNode.builder().maxParallelTools(Math.max(1, configuredLimit)).build();","handlingStrategy":"validation","validationCode":"if (maxParallelTools < 1) throw new IllegalArgumentException(\"maxParallelTools must be >= 1\");","typeGuard":"int safeParallelism(Integer cfg) { return (cfg == null || cfg < 1) ? 5 : cfg; }","tryCatchPattern":"try { b.maxParallelTools(n); } catch (IllegalArgumentException e) { b.maxParallelTools(5); log.warn(\"Reset maxParallelTools to default\"); }","preventionTips":["Use maxParallelTools(1) for sequential execution, never 0","Apply a default (5) when the config value is missing or invalid","Clamp derived values: Math.max(1, computed)"],"tags":["java","validation","builder","parallelism"],"backgroundTag":"argument-out-of-range","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}