JuliusBrussee/caveman · error

cave_claude_output_budget_too_small_for_reasoning

cave_claude_output_budget_too_small_for_reasoning

Error message

cave_claude_output_budget_too_small_for_reasoning

What it means

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.

Solutions

1. Raise outputMaxTokens above the reasoning budget (e.g. > 8192 for high reasoning).
2. Set the agent's reasoning to "off" if extended thinking is not needed.
3. Use a lower reasoning level ("low" needs only > 1024 output tokens).

Example fix

// before
run(agent, { outputMaxTokens: 2048 }); // reasoning: "medium" needs > 4096
// after
run(agent, { outputMaxTokens: 8192 });

const budgets = { low: 1024, medium: 4096, high: 8192 };
function assertOutputFitsReasoning(outputMaxTokens, reasoning) {
  if (reasoning === "off") return;
  const needed = budgets[reasoning ?? "low"];
  if (outputMaxTokens !== undefined && outputMaxTokens <= needed) {
    throw new Error(`outputMaxTokens must be > ${needed} for reasoning "${reasoning}"`);
  }
}

try {
  await run(agent, { outputMaxTokens });
} catch (e) {
  if (e.message === "cave_claude_output_budget_too_small_for_reasoning") {
    return run(agent, { outputMaxTokens: 16384 });
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• cave_claude_provider_unsupported
• cave_claude_reasoning_capability_unknown
• caveman agent: invalid .caveman/provider.json
• aes cipher
• apiKey, baseURL, and agent are required

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/716979266ff52b74. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/claude-runtime.ts:514

}

function claudeReasoningOptions(
  model: string,
  reasoning: AgentDefinition["reasoning"],
  outputMaxTokens: number | undefined,
): Pick<ClaudeSDKOptions, "thinking" | "effort"> {
  if (reasoning === "off") return { thinking: { type: "disabled" } };
  const capability = claudeThinkingCapability(model);
  if (capability === "adaptive") {
    return {
      thinking: { type: "adaptive" },
      effort: claudeEffort(reasoning),
    };
  }
  if (capability === "manual") {
    const budgetTokens = reasoning === "high" ? 8_192 : reasoning === "medium" ? 4_096 : 1_024;
    if (outputMaxTokens !== undefined && outputMaxTokens <= budgetTokens) {
      throw new Error("cave_claude_output_budget_too_small_for_reasoning");
    }
    return { thinking: { type: "enabled", budgetTokens } };
  }
  throw new Error(`cave_claude_reasoning_capability_unknown:${model}`);
}

function claudeThinkingCapability(model: string): "adaptive" | "manual" | "unknown" {
  if (/^claude-(?:haiku-4-5|sonnet-4-5|opus-4-(?:1|5))(?:-\d{8})?$/.test(model)) {
    return "manual";
  }
  if (/^claude-(?:sonnet|opus)-4-[678](?:-\d{8})?$/.test(model) ||
      /^claude-(?:fable|mythos|sonnet|opus)-5(?:-\d+)?$/.test(model)) {
    return "adaptive";
  }
  return "unknown";
}

// Accepts ANY result subtype: error subtypes (error_max_turns, …) carry the

View on GitHub (pinned to 3ee70a1026)