{"record":{"id":"0c1a6632e913f1d6","repo":"n8n-io/n8n","slug":"toolcallconcurrency-must-be-a-positive-integer-or","errorCode":null,"errorMessage":"toolCallConcurrency must be a positive integer or Infinity","messagePattern":"toolCallConcurrency must be a positive integer or Infinity","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/agents/src/sdk/agent.ts","lineNumber":548,"sourceCode":"\t\t}\n\t\treturn this;\n\t}\n\n\t/** @internal Read the declared telemetry builder (used by the execution engine to resolve credentials). */\n\tprotected get declaredTelemetry(): Telemetry | undefined {\n\t\treturn this.telemetryBuilder;\n\t}\n\n\t/**\n\t * Set the number of tool calls to execute concurrently within a single LLM turn.\n\t *\n\t * - `1` (default) — sequential execution, fully backward-compatible.\n\t * - `Infinity` — unlimited parallelism (all tool calls start at once).\n\t * - Any number in between — bounded concurrency (e.g. `5` = at most 5 tools run simultaneously).\n\t */\n\ttoolCallConcurrency(n: number): this {\n\t\tif ((n !== Infinity && !Number.isInteger(n)) || n < 1) {\n\t\t\tthrow new Error('toolCallConcurrency must be a positive integer or Infinity');\n\t\t}\n\t\tthis.concurrencyValue = n;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Attach a workspace to this agent. Workspace tools and instructions\n\t * are injected at build time.\n\t */\n\tworkspace(ws: Workspace): this {\n\t\tthis.workspaceInstance = ws;\n\t\treturn this;\n\t}\n\n\t/**\n\t * Add an MCP client as a tool source for this agent.\n\t * Tools from all servers in the client become available to the agent.\n\t * Multiple clients can be added; tools are merged across all of them.","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/agents/src/sdk/agent.ts#L530-L566","documentation":"Thrown by Agent.toolCallConcurrency(n) when n is not a positive integer and not Infinity. The check rejects zero, negative numbers, fractional numbers, NaN, and non-integer values. This controls how many tool calls within a single LLM turn execute in parallel, so it must be a valid positive count.","triggerScenarios":"Calling agent.toolCallConcurrency(0), toolCallConcurrency(-1), toolCallConcurrency(2.5), toolCallConcurrency(NaN), or passing a value from user input that was not validated as a positive integer.","commonSituations":"Reading concurrency from an environment variable or config file without parsing or validating (e.g. parseInt returning NaN for a missing value). Defaulting to 0 meaning 'disabled'. Passing a float from a slider or ratio calculation. Distinguishing 'sequential' (1) from 'off' (0) incorrectly.","solutions":["Pass 1 for sequential execution (the default), a positive integer for bounded concurrency, or Infinity for unlimited.","If reading from config, validate and coerce: const n = parseInt(raw, 10); if (Number.isInteger(n) && n >= 1) agent.toolCallConcurrency(n).","Use a fallback default of 1 when the config value is missing or invalid."],"exampleFix":"// before\nconst raw = process.env.TOOL_CONCURRENCY; // undefined or '0'\nagent.toolCallConcurrency(parseInt(raw)); // NaN or 0 -> throws\n// after\nconst n = Number.parseInt(process.env.TOOL_CONCURRENCY ?? '1', 10);\nagent.toolCallConcurrency(Number.isFinite(n) && n >= 1 ? n : 1);","handlingStrategy":"validation","validationCode":"function isValidConcurrency(n: unknown): boolean {\n  return n === Infinity || (typeof n === 'number' && Number.isInteger(n) && n >= 1);\n}\nconst concurrency = isValidConcurrency(rawValue) ? (rawValue as number) : 1;\nagent.toolCallConcurrency(concurrency);","typeGuard":"function isPositiveIntegerOrInfinity(n: unknown): n is number {\n  return n === Infinity || (typeof n === 'number' && Number.isInteger(n) && n >= 1);\n}","tryCatchPattern":null,"preventionTips":["Validate concurrency values from env vars or config files before passing them.","Default to 1 when the source value is missing, NaN, or invalid.","Use Number.isInteger() checks for config-derived integers."],"tags":["concurrency","validation","configuration","agent"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}