coleam00/Archon · error

Node '${node.id}' exceeded cost cap${cap !== undefined ? ` o

Error message

Node '${node.id}' exceeded cost cap${cap !== undefined ? ` of $${cap.toFixed(2)}` : ''}.

What it means

Thrown when the SDK reports an error_max_budget_usd result for an agent node, meaning the node consumed more than its configured maxBudgetUsd cost cap. The executor fails the node loudly (after logging dag.node_budget_cap_exceeded) instead of treating the capped stop as success, because partial output would masquerade as a completed run.

Source

Thrown at packages/workflows/src/dag-executor.ts:2627

          }
        }
        if (msg.stopReason !== undefined) nodeStopReason = msg.stopReason;
        if (msg.numTurns !== undefined) nodeNumTurns = msg.numTurns;
        // Assigned UNCONDITIONALLY. A guarded assignment cannot CLEAR a stale value:
        // Pi/Copilot reask loops yield several result chunks, and Pi omits resolvedModel
        // when its later assistant message has no responseModel — so an earlier attempt's
        // model would be persisted as the final attempt's answer. Fabricated attribution
        // is the exact defect #2314 exists to prevent; absence must stay absence.
        nodeResolvedModel = msg.resolvedModel;
        if (msg.structuredOutput !== undefined) structuredOutput = msg.structuredOutput;
        // Fail the node if the SDK reports a cost cap exceeded error
        if (msg.isError && msg.errorSubtype === 'error_max_budget_usd') {
          const cap = nodeOptions?.maxBudgetUsd;
          getLog().warn(
            { nodeId: node.id, maxBudgetUsd: cap, durationMs: Date.now() - nodeStartTime },
            'dag.node_budget_cap_exceeded'
          );
          throw new Error(
            `Node '${node.id}' exceeded cost cap${cap !== undefined ? ` of $${cap.toFixed(2)}` : ''}.`
          );
        }
        // Fail loudly on any other SDK error result. Previously we broke out of
        // the stream silently, producing empty/partial output without signaling
        // failure — which let failed iterations masquerade as successes.
        // Exception: errorSubtype === 'success' is the Claude SDK's marker for a
        // clean stop_sequence termination. The Claude provider already filters
        // this out, but the guard here keeps a third-party IAgentProvider that
        // forwards the SDK pair raw from producing a "SDK returned success"
        // false failure.
        if (msg.isError && msg.errorSubtype !== 'success') {
          const subtype = msg.errorSubtype ?? 'unknown';
          const errorsDetail = msg.errors?.length ? ` — ${msg.errors.join('; ')}` : '';
          getLog().error(
            {
              nodeId: node.id,
              errorSubtype: subtype,

View on GitHub (pinned to 0773b97458)

Solutions

  1. Raise maxBudgetUsd on the node options to a realistic ceiling.
  2. Reduce token consumption: trim prompts/context, use a cheaper model for the node, or cap iterations.
  3. Split the work across nodes so each has its own budget.
  4. If the cap was intentional, treat this failure as the designed safety stop and handle the node failure downstream.

Example fix

// before
options: { maxBudgetUsd: 0.5 }
// after
options: { maxBudgetUsd: 5.0 }
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check: estimate expected spend vs cap
if (nodeOptions.maxBudgetUsd !== undefined && nodeOptions.maxBudgetUsd < estimatedMinSpendUsd) {
  console.warn(`maxBudgetUsd ${nodeOptions.maxBudgetUsd} likely too low (est. min $${estimatedMinSpendUsd})`);
}

Type guard

function hasBudgetCap(o: unknown): o is { maxBudgetUsd: number } {
  return typeof o === 'object' && o !== null && 'maxBudgetUsd' in o && typeof (o as any).maxBudgetUsd === 'number';
}

Try / catch

try {
  await runNode(node);
} catch (e) {
  if (/exceeded cost cap/.test(String(e))) {
    log.warn('budget cap hit — raise maxBudgetUsd or reduce scope');
  } else throw e;
}

Prevention

When it happens

Trigger: A node's options set maxBudgetUsd and the underlying model SDK ended the turn with an error_max_budget_usd result because accumulated spend crossed the cap.

Common situations: Long agent loops burning tokens on a hard task; an unexpectedly expensive model or large context; a cap set too low for the task's realistic token usage.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/a2cb6974e90a5787. Report an issue: GitHub.