{"record":{"id":"716979266ff52b74","repo":"JuliusBrussee/caveman","slug":"cave-claude-output-budget-too-small-for-reasoning","errorCode":"cave_claude_output_budget_too_small_for_reasoning","errorMessage":"cave_claude_output_budget_too_small_for_reasoning","messagePattern":"cave_claude_output_budget_too_small_for_reasoning","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/claude-runtime.ts","lineNumber":514,"sourceCode":"}\n\nfunction claudeReasoningOptions(\n  model: string,\n  reasoning: AgentDefinition[\"reasoning\"],\n  outputMaxTokens: number | undefined,\n): Pick<ClaudeSDKOptions, \"thinking\" | \"effort\"> {\n  if (reasoning === \"off\") return { thinking: { type: \"disabled\" } };\n  const capability = claudeThinkingCapability(model);\n  if (capability === \"adaptive\") {\n    return {\n      thinking: { type: \"adaptive\" },\n      effort: claudeEffort(reasoning),\n    };\n  }\n  if (capability === \"manual\") {\n    const budgetTokens = reasoning === \"high\" ? 8_192 : reasoning === \"medium\" ? 4_096 : 1_024;\n    if (outputMaxTokens !== undefined && outputMaxTokens <= budgetTokens) {\n      throw new Error(\"cave_claude_output_budget_too_small_for_reasoning\");\n    }\n    return { thinking: { type: \"enabled\", budgetTokens } };\n  }\n  throw new Error(`cave_claude_reasoning_capability_unknown:${model}`);\n}\n\nfunction claudeThinkingCapability(model: string): \"adaptive\" | \"manual\" | \"unknown\" {\n  if (/^claude-(?:haiku-4-5|sonnet-4-5|opus-4-(?:1|5))(?:-\\d{8})?$/.test(model)) {\n    return \"manual\";\n  }\n  if (/^claude-(?:sonnet|opus)-4-[678](?:-\\d{8})?$/.test(model) ||\n      /^claude-(?:fable|mythos|sonnet|opus)-5(?:-\\d+)?$/.test(model)) {\n    return \"adaptive\";\n  }\n  return \"unknown\";\n}\n\n// Accepts ANY result subtype: error subtypes (error_max_turns, …) carry the","sourceCodeStart":496,"sourceCodeEnd":532,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/claude-runtime.ts#L496-L532","documentation":"For models with \"manual\" extended-thinking capability (claude-haiku-4-5, sonnet-4-5, opus-4-1/4-5), claudeReasoningOptions allocates a thinking budget (1024/4096/8192 tokens for low/medium/high reasoning). If the caller set outputMaxTokens at or below that budget, thinking would consume the entire output allowance, so the runtime throws instead of producing a broken request.","triggerScenarios":"Running a Claude agent with reasoning enabled (not \"off\") on a manual-thinking model while outputMaxTokens <= the derived budget, e.g. reasoning \"medium\" (budget 4096) with outputMaxTokens 4096 or less.","commonSituations":"Setting maxTokens to a small value like 1024 or 2048 to save cost while leaving the agent's reasoning setting at its default; a template definition that lowers output tokens without disabling thinking.","solutions":["Raise outputMaxTokens above the reasoning budget (e.g. > 8192 for high reasoning).","Set the agent's reasoning to \"off\" if extended thinking is not needed.","Use a lower reasoning level (\"low\" needs only > 1024 output tokens)."],"exampleFix":"// before\nrun(agent, { outputMaxTokens: 2048 }); // reasoning: \"medium\" needs > 4096\n// after\nrun(agent, { outputMaxTokens: 8192 });","handlingStrategy":"validation","validationCode":"const budgets = { low: 1024, medium: 4096, high: 8192 };\nfunction assertOutputFitsReasoning(outputMaxTokens, reasoning) {\n  if (reasoning === \"off\") return;\n  const needed = budgets[reasoning ?? \"low\"];\n  if (outputMaxTokens !== undefined && outputMaxTokens <= needed) {\n    throw new Error(`outputMaxTokens must be > ${needed} for reasoning \"${reasoning}\"`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await run(agent, { outputMaxTokens });\n} catch (e) {\n  if (e.message === \"cave_claude_output_budget_too_small_for_reasoning\") {\n    return run(agent, { outputMaxTokens: 16384 });\n  }\n  throw e;\n}","preventionTips":["Keep outputMaxTokens at least 2x the reasoning budget you configure","Disable reasoning (reasoning: \"off\") when you need small output caps","Document the minimum token budget in your agent templates"],"tags":["claude","reasoning","token-budget","configuration"],"backgroundTag":"value-out-of-range","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"}