{"record":{"id":"7d2b59a07608f709","repo":"run-llama/llama_index","slug":"token-budget-exceeded-limit-self-token-budget","errorCode":null,"errorMessage":"Token budget exceeded! Limit: {self.token_budget}, Current: {self.total_llm_token_count}","messagePattern":"Token budget exceeded! Limit: (.+?), Current: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/callbacks/token_counting.py","lineNumber":198,"sourceCode":"            logger=logger,\n        )\n\n    def start_trace(self, trace_id: Optional[str] = None) -> None:\n        return\n\n    def end_trace(\n        self,\n        trace_id: Optional[str] = None,\n        trace_map: Optional[Dict[str, List[str]]] = None,\n    ) -> None:\n        return\n\n    def _check_budget(self) -> None:\n        if (\n            self.token_budget is not None\n            and self.total_llm_token_count > self.token_budget\n        ):\n            raise ValueError(\n                f\"Token budget exceeded! Limit: {self.token_budget}, \"\n                f\"Current: {self.total_llm_token_count}\"\n            )\n\n    def on_event_start(\n        self,\n        event_type: CBEventType,\n        payload: Optional[Dict[str, Any]] = None,\n        event_id: str = \"\",\n        parent_id: str = \"\",\n        **kwargs: Any,\n    ) -> str:\n        self._check_budget()\n        return event_id\n\n    def on_event_end(\n        self,\n        event_type: CBEventType,","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/callbacks/token_counting.py#L180-L216","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nhandler = TokenCountingHandler(token_budget=1000)  # blows up after ~1 query\nSettings.callback_manager.add_handler(handler)\nquery_engine.query('...')  # ValueError: Token budget exceeded!\n\n# after\nhandler = TokenCountingHandler(token_budget=1_000_000)\nSettings.callback_manager.add_handler(handler)\nfor q in questions:\n    query_engine.query(q)\n    if handler.total_llm_token_count > 500_000:\n        break  # soft checkpoint instead of crashing","handlingStrategy":"try-catch","validationCode":"if handler.token_budget is not None and handler.total_llm_token_count >= handler.token_budget:\n    logger.warning('Token budget nearly exhausted: %d/%d', handler.total_llm_token_count, handler.token_budget)","typeGuard":null,"tryCatchPattern":"from llama_index.core.callbacks import TokenCountingHandler\ntry:\n    result = query_engine.query(q)\nexcept ValueError as e:\n    if 'Token budget exceeded' in str(e):\n        handler.reset_count()  # or checkpoint-and-stop the batch\n        raise BudgetExhausted from e\n    raise","preventionTips":["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"],"tags":["llama-index","callbacks","token-limit","cost-control"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}