{"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":"Error","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/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/index.ts#L167-L203","documentation":"Thrown by the subagent tool factory when the effective maxContextTokens value is not a safe positive integer. This bounds how much context the subagent run may accumulate before truncation/compaction; it defaults to 128_000, so the error fires only when you override it with an invalid value.","triggerScenarios":"Passing maxContextTokens: 0, a negative number, a float such as 128000.5, NaN, or a string. Also fires when computing the value from model metadata that yields undefined math (NaN).","commonSituations":"Sizing the context window from a model spec object whose field is missing (undefined arithmetic -> NaN), copying a provider's context length that includes a 'k' suffix (\"128k\"), or reusing a value tuned for a different library that allowed 0 as 'auto'.","solutions":["Pass a positive safe integer, e.g. maxContextTokens: 128_000","Omit the option to keep the 128_000 default","Map model specs defensively: const ctx = Number.isSafeInteger(spec.contextWindow) && spec.contextWindow > 0 ? spec.contextWindow : 128_000","Strip suffixes and round before passing: Math.round(parseInt(raw, 10))"],"exampleFix":"// before\nsubagentTool({ agent, name: \"worker\", maxContextTokens: Number(spec[\"context-window\"]) }); // \"128k\" -> NaN\n\n// after\nconst ctx = Number.isSafeInteger(spec.contextWindow) && spec.contextWindow > 0\n  ? spec.contextWindow\n  : 128_000;\nsubagentTool({ agent, name: \"worker\", maxContextTokens: ctx });","handlingStrategy":"validation","validationCode":"const ctx = Number(cfg.contextWindow);\nconst maxContextTokens = Number.isSafeInteger(ctx) && ctx > 0 ? ctx : 128_000;\nsubagentTool({ agent, name: \"worker\", maxContextTokens });","typeGuard":"const isPositiveInt = (v: unknown): v is number =>\n  Number.isSafeInteger(v) && (v as number) > 0;","tryCatchPattern":null,"preventionTips":["Parse 'k'/'m' suffixed specs (\"128k\") into plain integers before use","Fallback to the library default (128_000) when model metadata is missing rather than passing NaN","Add a table mapping each model id to its integer context window"],"tags":["subagent","validation","context-window","configuration"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}