paperclipai/paperclip · error

estimated cost limit exceeded

Error message

estimated cost limit exceeded

What it means

runEvalSessionCli enforces a cost ceiling after the provider turn completes. evalSessionUsage derives estimatedCostNanodollars from token usage in the turn snapshot; if it exceeds request.limits.maxEstimatedCostNanodollars the run is aborted so an eval session cannot silently overspend.

Source

Thrown at packages/paperclip-runner/src/cli/eval-session.ts:249

  }
}

export function boundedEvalSessionUsage(
  request: EvalSessionRequest,
  turn: CapabilityLiveTurnResult,
): EvalSessionUsage | null {
  if (turn.status !== "completed") {
    return usageIfAvailable(request, turn.snapshot);
  }
  const usage = evalSessionUsage(request.model, turn.snapshot);
  if (usage.agentTurns > request.limits.maxAgentTurns) {
    throw new Error("agent turn limit exceeded");
  }
  if (
    usage.estimatedCostNanodollars >
    request.limits.maxEstimatedCostNanodollars
  ) {
    throw new Error("estimated cost limit exceeded");
  }
  if (
    usage.providerReportedCostNanodollars >
    request.limits.maxEstimatedCostNanodollars
  ) {
    throw new Error("provider-reported cost limit exceeded");
  }
  return usage;
}

async function closeSession(
  session: CapabilityLiveSession | null,
  reason: string,
): Promise<void> {
  if (session === null || session.snapshot().status === "closed") return;
  await session.shutdown(reason);
}

View on GitHub (pinned to 01ad858492)

Solutions

1. Raise request.limits.maxEstimatedCostNanodollars to match the model's expected cost
2. Use a cheaper model/requestedModel for the eval
3. Reduce prompt/output size (trim context, cap tool outputs)
4. Verify the nanodollar arithmetic — 1 dollar = 1e9 nanodollars — when setting limits

Example fix

// before
limits: { maxEstimatedCostNanodollars: 1_000_000, ... } // $0.001
// after
limits: { maxEstimatedCostNanodollars: 100_000_000, ... } // $0.10

// Estimate cost before the run and pre-validate the budget
const maxPromptTokens = request.prompt.length / 4;
const worstCaseTokens = (maxPromptTokens + 10_000) * request.limits.maxAgentTurns;
const worstCaseNanodollars = worstCaseTokens * pricePerTokenNanodollars(request.model);
if (worstCaseNanodollars > request.limits.maxEstimatedCostNanodollars) {
  throw new Error(`budget ${request.limits.maxEstimatedCostNanodollars} nd too low; worst case ~${worstCaseNanodollars} nd`);
}

try {
  await runEvalSessionCli(request, cli);
} catch (error) {
  if (error instanceof Error && error.message === "estimated cost limit exceeded") {
    console.error(`cost cap hit: estimated=${usage.estimatedCostNanodollars} nd, cap=${request.limits.maxEstimatedCostNanodollars} nd`);
    // raise cap or downgrade model, then retry
  }
  throw error;
}

When it happens

Trigger: usage.estimatedCostNanodollars > request.limits.maxEstimatedCostNanodollars in runEvalSessionCli — i.e. the estimated (token-derived) cost of the completed turn exceeded the configured budget.

Common situations: maxEstimatedCostNanodollars set too low for the model's token pricing; long prompts or large tool outputs inflating token counts; switching to a more expensive model without raising the limit; unit mistakes (nanodollars vs dollars) when configuring limits.

Related errors

• provider-reported cost limit exceeded
• agent turn limit exceeded
• remote session budget updates require a connected remote pro
• managed session spend ceiling must be positive
• paperclip_runner_claude_managed_spend_cap_invalid

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/b6f5ef4a9b9d3168. Report an issue: GitHub.