{"record":{"id":"072ed9e10e3ec079","repo":"JuliusBrussee/caveman","slug":"cave-subagent-concurrency-limit-invalid","errorCode":"cave_subagent_concurrency_limit_invalid","errorMessage":"cave_subagent_concurrency_limit_invalid","messagePattern":"cave_subagent_concurrency_limit_invalid","errorType":"error_code","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/agent/src/runtime.ts","lineNumber":1067,"sourceCode":"    },\n  } as AsyncGenerator<CavemanRunEvent>;\n}\n\nasync function* streamAgentInternal(\n  definition: AgentDefinition,\n  input: string,\n  options: InternalRunOptions,\n  executionContext: InternalExecutionContext,\n): AsyncGenerator<CavemanRunEvent> {\n  if (options.maxSubagentInvocations !== undefined &&\n      (!Number.isSafeInteger(options.maxSubagentInvocations) || options.maxSubagentInvocations <= 0 ||\n        options.maxSubagentInvocations > ABSOLUTE_SUBAGENT_INVOCATION_LIMIT)) {\n    throw new Error(\"cave_subagent_invocation_limit_invalid\");\n  }\n  if (options.maxConcurrentSubagents !== undefined &&\n      (!Number.isSafeInteger(options.maxConcurrentSubagents) || options.maxConcurrentSubagents <= 0 ||\n        options.maxConcurrentSubagents > ABSOLUTE_SUBAGENT_INVOCATION_LIMIT)) {\n    throw new Error(\"cave_subagent_concurrency_limit_invalid\");\n  }\n  if (options.lockedBuild !== undefined && options.candidatePlan !== undefined) {\n    throw new Error(\"cave_execution_authorization_ambiguous\");\n  }\n  // Budget shape is settled before anything else happens: an ambiguous or\n  // unbounded budget must fail at run() start, not after the first dollar.\n  // maxCostUsd and budget are two different contracts for the same money —\n  // one terminates with an error, the other returns a planned partial result —\n  // so carrying both would leave the run's own stop semantics undecided.\n  if (options.budget !== undefined && options.maxCostUsd !== undefined) {\n    throw new Error(\"cave_budget_conflicting_cap\");\n  }\n  const budgetMeter = executionContext.budgetMeter ?? (options.budget === undefined\n    ? undefined\n    : new BudgetMeter(normalizeRunBudget(options.budget)));\n  if (options.deadlineMs !== undefined &&\n      (!Number.isSafeInteger(options.deadlineMs) || options.deadlineMs <= 0)) {\n    throw new Error(\"cave_run_deadline_invalid\");","sourceCodeStart":1049,"sourceCodeEnd":1085,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/runtime.ts#L1049-L1085","documentation":"RunOptions.maxConcurrentSubagents caps simultaneously active descendant subagents. streamAgentInternal validates it at run start: it must be a safe integer > 0 and at most ABSOLUTE_SUBAGENT_INVOCATION_LIMIT (1,000,000). Invalid values throw before any execution begins.","triggerScenarios":"Calling runAgent/streamAgent with options.maxConcurrentSubagents set to 0, a negative number, a non-integer, NaN/Infinity, or a value above 1,000,000.","commonSituations":"Env/JSON-derived config parsed as float or string; a \"no concurrency\" intent expressed as 0 instead of omitting the option; formula-generated caps producing 0 or fractional values.","solutions":["Pass a positive safe integer between 1 and 1,000,000 for maxConcurrentSubagents.","Validate/clamp the value before the call: Math.max(1, Math.floor(v)).","Omit the option to leave concurrency uncapped by this control."],"exampleFix":"// before\nrunAgent(def, input, { maxConcurrentSubagents: opts.parallel });\n// after\nconst p = Math.floor(Number(opts.parallel));\nrunAgent(def, input, Number.isSafeInteger(p) && p > 0\n  ? { maxConcurrentSubagents: p }\n  : {});","handlingStrategy":"validation","validationCode":"function isValidConcurrencyLimit(v) {\n  return v === undefined || (Number.isSafeInteger(v) && v > 0 && v <= 1_000_000);\n}","typeGuard":"function hasValidMaxConcurrentSubagents(o) {\n  return o.maxConcurrentSubagents === undefined ||\n    (Number.isSafeInteger(o.maxConcurrentSubagents) && o.maxConcurrentSubagents > 0);\n}","tryCatchPattern":"try {\n  await runAgent(def, input, opts);\n} catch (err) {\n  if (err.message === \"cave_subagent_concurrency_limit_invalid\") {\n    opts.maxConcurrentSubagents = Math.max(1, Math.floor(Number(opts.maxConcurrentSubagents)) || 1);\n  } else throw err;\n}","preventionTips":["Express \"no cap\" by omitting the option, never with 0.","Floor fractional computed values before assignment.","Centralize option construction in one validated helper."],"tags":["agent-runtime","validation","options","concurrency"],"backgroundTag":"invalid-argument-value","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}