run-llama/llama_index · error · ValueError

Token budget exceeded! Limit: {self.token_budget}, Current:

Error message

Token budget exceeded! Limit: {self.token_budget}, Current: {self.total_llm_token_count}

What it means

Raised by TokenCountingHandler._check_budget() when the cumulative LLM token count tracked by the handler exceeds the token_budget you configured. The handler counts prompt+completion tokens across all LLM events and enforces the cap by raising ValueError, turning the budget into a hard circuit breaker rather than a soft warning.

Source

Thrown at llama-index-core/llama_index/core/callbacks/token_counting.py:198

            logger=logger,
        )

    def start_trace(self, trace_id: Optional[str] = None) -> None:
        return

    def end_trace(
        self,
        trace_id: Optional[str] = None,
        trace_map: Optional[Dict[str, List[str]]] = None,
    ) -> None:
        return

    def _check_budget(self) -> None:
        if (
            self.token_budget is not None
            and self.total_llm_token_count > self.token_budget
        ):
            raise ValueError(
                f"Token budget exceeded! Limit: {self.token_budget}, "
                f"Current: {self.total_llm_token_count}"
            )

    def on_event_start(
        self,
        event_type: CBEventType,
        payload: Optional[Dict[str, Any]] = None,
        event_id: str = "",
        parent_id: str = "",
        **kwargs: Any,
    ) -> str:
        self._check_budget()
        return event_id

    def on_event_end(
        self,
        event_type: CBEventType,

View on GitHub (pinned to afd0fef371)

Solutions

Raise token_budget to a realistic value based on expected run length (e.g. queries * average tokens per query)
Reset the handler counters between logical runs with handler.reset_count() so totals do not accumulate across jobs
Reduce token consumption: smaller top_k, tighter retrieval, shorter chat memory (memory token_limit), or a cheaper model
Set token_budget=None if you only want counting (handler.total_llm_token_count) without enforcement

Example fix

# before
handler = TokenCountingHandler(token_budget=1000)  # blows up after ~1 query
Settings.callback_manager.add_handler(handler)
query_engine.query('...')  # ValueError: Token budget exceeded!

# after
handler = TokenCountingHandler(token_budget=1_000_000)
Settings.callback_manager.add_handler(handler)
for q in questions:
    query_engine.query(q)
    if handler.total_llm_token_count > 500_000:
        break  # soft checkpoint instead of crashing

Defensive patterns

Strategy: try-catch

Validate before calling

if handler.token_budget is not None and handler.total_llm_token_count >= handler.token_budget:
    logger.warning('Token budget nearly exhausted: %d/%d', handler.total_llm_token_count, handler.token_budget)

Try / catch

from llama_index.core.callbacks import TokenCountingHandler
try:
    result = query_engine.query(q)
except ValueError as e:
    if 'Token budget exceeded' in str(e):
        handler.reset_count()  # or checkpoint-and-stop the batch
        raise BudgetExhausted from e
    raise

Prevention

Reset handler counters between jobs with handler.reset_count()
Size token_budget from measured average tokens per query times planned query count
Poll total_llm_token_count as a soft gauge and checkpoint long jobs instead of relying on the hard raise

When it happens

Trigger: Constructing TokenCountingHandler(token_budget=N, ...) and attaching it to Settings.callback_manager, then running enough queries (or one very large-context query) that total_llm_token_count exceeds N; the check fires on the next event hook after the limit is crossed.

Common situations: Cost-control guardrails in batch indexing or evaluation jobs; long-running agents whose history grows until each turn pushes past the budget; budgets set below the context size of a single LLM call so the first request already fails.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/7d2b59a07608f709. Report an issue: GitHub.