{"record":{"id":"9cb7147ebb85e7d8","repo":"JuliusBrussee/caveman","slug":"caveman-agent-subagent-maxcontexttokens-must-be-a","errorCode":null,"errorMessage":"caveman agent: subagent maxContextTokens must be a positive integer","messagePattern":"caveman agent: subagent maxContextTokens must be a positive integer","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/index.ts","lineNumber":185,"sourceCode":"  const maxInputChars = options.maxInputChars ?? 32_768;\n  if (!Number.isSafeInteger(maxInputChars) || maxInputChars <= 0) {\n    throw new Error(\"caveman agent: subagent maxInputChars must be a positive integer\");\n  }\n  const maxCalls = options.maxCalls ?? 1;\n  const maxCostUsd = options.maxCostUsd ?? 1;\n  const maxContextTokens = options.maxContextTokens ?? 128_000;\n  if (!Number.isSafeInteger(maxCalls) || maxCalls <= 0) {\n    throw new Error(\"caveman agent: subagent maxCalls must be a positive integer\");\n  }\n  if (!Number.isFinite(maxCostUsd) || maxCostUsd <= 0) {\n    throw new Error(\"caveman agent: subagent maxCostUsd must be positive\");\n  }\n  if (options.maxTokens !== undefined &&\n      (!Number.isSafeInteger(options.maxTokens) || options.maxTokens <= 0)) {\n    throw new Error(\"caveman agent: subagent maxTokens must be a positive integer\");\n  }\n  if (!Number.isSafeInteger(maxContextTokens) || maxContextTokens <= 0) {\n    throw new Error(\"caveman agent: subagent maxContextTokens must be a positive integer\");\n  }\n  return tool({\n    name: options.name,\n    description: options.description,\n    input: schema.object({ task: schema.string() }),\n    effect: \"read\",\n    result: \"auto\",\n    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),\n    runtime: {\n      kind: \"subagent\",\n      definition: options.agent,\n      maxInputChars,\n      maxCalls,\n      maxCostUsd,\n      ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),\n      maxContextTokens,\n    },\n    async execute() {","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/index.ts#L167-L203","documentation":"`subagent()` validates `maxContextTokens`, which defaults to 128,000 and bounds the subagent's context window usage. It must be a positive safe integer (this option, unlike maxTokens, has no undefined escape — the resolved default is always checked). The library throws at tool-creation time for 0, negatives, floats, NaN, or values above Number.MAX_SAFE_INTEGER.","triggerScenarios":"Calling `subagent({ maxContextTokens: 0 })`, `subagent({ maxContextTokens: -1 })`, `subagent({ maxContextTokens: 128000.5 })`, `subagent({ maxContextTokens: NaN })`, or passing a numeric string from config.","commonSituations":"Reading the value from a JSON/ENV config as a string; unit confusion between tokens and characters producing fractions; copying a model context size with a comma ('128,000') that fails numeric parsing.","solutions":["Pass a positive integer, e.g. `subagent({ maxContextTokens: 200_000 })`, or omit it to use the 128,000 default.","Coerce and validate config: `const v = Number.parseInt(raw, 10)`; check `Number.isSafeInteger(v) && v > 0`.","Match the value to your model provider's actual context window to avoid later runtime limits."],"exampleFix":"// before\nsubagent({ name: \"reader\", maxContextTokens: \"200,000\" })\n// after\nsubagent({ name: \"reader\", maxContextTokens: 200_000 })","handlingStrategy":"validation","validationCode":"const assertContextTokens = (v) => {\n  const n = typeof v === \"string\" ? Number.parseInt(v.replaceAll(\",\", \"\"), 10) : v;\n  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`maxContextTokens must be a positive integer, got ${v}`);\n  return n;\n};\nsubagent({ name: \"reader\", maxContextTokens: assertContextTokens(cfg.maxContextTokens) });","typeGuard":"const isPosInt = (v) => typeof v === \"number\" && Number.isSafeInteger(v) && v > 0;","tryCatchPattern":"try {\n  const t = subagent({ maxContextTokens: cfg.maxContextTokens });\n} catch (e) {\n  if (e.message.includes(\"maxContextTokens must be a positive integer\")) {\n    console.error(`Bad maxContextTokens: ${JSON.stringify(cfg.maxContextTokens)}; using default 128000`);\n    return subagent({ name: \"reader\" }); // falls back to library default\n  }\n  throw e;\n}","preventionTips":["Strip formatting (commas, underscores) before parsing token counts from config","Validate the value against your model provider's real context window","Keep this option in the same validated config object as maxTokens/maxCalls","Prefer the library default (128000) unless you have a reason to override"],"tags":["configuration","validation","argument-error"],"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"}