{"record":{"id":"716979266ff52b74","repo":"JuliusBrussee/caveman","slug":"cave-claude-output-budget-too-small-for-reasoning","errorCode":null,"errorMessage":"cave_claude_output_budget_too_small_for_reasoning","messagePattern":"cave_claude_output_budget_too_small_for_reasoning","errorType":"exception","errorClass":"Error","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/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/claude-runtime.ts#L496-L532","documentation":"For models with \"manual\" thinking capability (claude-haiku-4-5, sonnet-4-5, opus-4-1/4-5), the framework maps reasoning level to a thinking budget (high=8192, medium=4096, low=1024 tokens). If you also set outputMaxTokens and it is <= the thinking budget, the model would spend its entire output allowance on reasoning and have nothing left for the answer, so the option combination is rejected up front.","triggerScenarios":"Calling the Claude run with reasoning set to low/medium/high (not \"off\"), a manually-thinking model, and an options.outputMaxTokens <= 1024/4096/8192 respectively. Example: { reasoning: \"medium\", outputMaxTokens: 4000 } → 4000 <= 4096 → throw.","commonSituations":"Tightening outputMaxTokens to cap cost while leaving reasoning on; porting a config from an adaptive-thinking model (opus-4-6+, sonnet-5) where the constraint doesn't exist; defaults that set a small max_tokens from an older provider config.","solutions":["Raise outputMaxTokens above the reasoning budget: use > 8192 for reasoning:\"high\", > 4096 for \"medium\", > 1024 for \"low\".","Or set reasoning: \"off\" (thinking disabled) if a small output cap is the priority.","Or switch to an adaptive-thinking model (e.g. claude-sonnet-4-6, claude-sonnet-5) where effort-based thinking has no token-budget coupling."],"exampleFix":"// before\nawait run({ prompt, reasoning: \"medium\", outputMaxTokens: 4000 });\n\n// after\nawait run({ prompt, reasoning: \"medium\", outputMaxTokens: 16384 });\n// or: await run({ prompt, reasoning: \"off\", outputMaxTokens: 4000 });","handlingStrategy":"validation","validationCode":"const REASONING_BUDGET = { low: 1024, medium: 4096, high: 8192 } as const;\nfunction outputBudgetOk(reasoning: keyof typeof REASONING_BUDGET | \"off\", outputMaxTokens?: number): boolean {\n  if (reasoning === \"off\" || outputMaxTokens === undefined) return true;\n  return outputMaxTokens > REASONING_BUDGET[reasoning];\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Budget outputMaxTokens as thinking budget + comfortable answer room (e.g. >= 4x the reasoning budget).","When tightening output caps for cost, turn reasoning off rather than shrinking the budget below the thinking allocation.","Remember the constraint only applies to manual-thinking models (haiku/sonnet-4-5, opus-4-1/4-5) — adaptive models are exempt."],"tags":["configuration","reasoning","token-budget","claude-sdk"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}