calesthio/OpenMontage · error · BudgetExceededError

Reservation of ${estimated:.2f} exceeds usable budget ${self

Error message

Reservation of ${estimated:.2f} exceeds usable budget ${self.usable_budget_usd:.2f}

What it means

BudgetExceededError raised by CostTracker.reserve in CAP mode when estimated_usd exceeds usable_budget_usd (total budget minus already-spent/reserved amounts). CAP mode enforces the ceiling hard; in WARN mode the same condition only stamps budget_warning fields on the entry and continues. This is the tracker's real 'out of money' guard.

Source

Thrown at tools/cost_tracker.py:149

                    f"single-action threshold ${self.single_action_approval_usd:.2f}"
                )

        # Check new paid tool approval
        if self.require_approval_for_new_paid_tool and estimated > 0:
            if entry["tool"] not in self._approved_tools:
                if self.mode != BudgetMode.OBSERVE:
                    raise ApprovalRequiredError(
                        f"First paid use of tool {entry['tool']!r} requires approval"
                    )

        # Check budget
        if estimated > self.usable_budget_usd:
            message = (
                f"Reservation of ${estimated:.2f} exceeds usable budget "
                f"${self.usable_budget_usd:.2f}"
            )
            if self.mode == BudgetMode.CAP:
                raise BudgetExceededError(message)
            if self.mode == BudgetMode.WARN:
                entry["budget_warning"] = True
                entry["budget_warning_message"] = message

        entry["status"] = EntryStatus.RESERVED.value
        entry["reserved_usd"] = estimated
        entry["timestamp"] = self._now()
        self._save()

    def approve_tool(self, tool: str) -> None:
        """Mark a tool as approved for paid operations."""
        self._approved_tools.add(tool)
        self._save()

    def reconcile(self, entry_id: str, actual_usd: float, success: bool = True) -> None:
        """Reconcile actual spend after tool execution."""
        entry = self._find(entry_id)
        entry["status"] = EntryStatus.COMPLETED.value if success else EntryStatus.FAILED.value

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Release or settle stale RESERVED entries you no longer need so usable_budget_usd is recomputed from actual spend.
2. Raise budget_total_usd to match the workload.
3. Switch mode to WARN if you want warnings instead of hard stops (entry gets budget_warning flags instead of an exception).
4. Reduce the action's cost (cheaper model, shorter output) or skip it until other reservations complete.

Example fix

# before
tracker.reserve(entry_id)  # CAP mode, estimate 0.80 > usable 0.50 -> BudgetExceededError

# after
from tools.cost_tracker import BudgetMode
tracker.mode = BudgetMode.WARN
tracker.reserve(entry_id)  # warns (entry['budget_warning']=True) instead of raising

def fits_budget(tracker, entry_id: str) -> bool:
    entry = next(e for e in tracker.entries if e["id"] == entry_id)
    return entry["estimated_usd"] <= tracker.usable_budget_usd

from tools.cost_tracker import BudgetExceededError

try:
    tracker.reserve(entry_id)
except BudgetExceededError:
    skip_or_queue_action()  # do not proceed with the paid call

When it happens

Trigger: reserve(entry_id) with mode == CAP and estimated > usable_budget_usd. Happens when cumulative reservations approach budget_total_usd and a new action does not fit in the remainder.

Common situations: Long batch runs where many small costs accumulate until the remainder is smaller than the next action's estimate; budget_total_usd set too low for the workload; stale reserved entries never released eating usable budget.

Related errors

• Action costs ${estimated:.2f}, exceeds single-action thresho
• First paid use of tool {entry['tool']!r} requires approval
• Cost entry {entry_id!r} not found
• pricing is unknown for a custom Ark Endpoint/Model; set cust

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/2f097eb2e0ea0c86. Report an issue: GitHub.