{"record":{"id":"b40a8a4f46dbeb49","repo":"BerriAI/litellm","slug":"contextwindowexceedederror-exception-provider","errorCode":null,"errorMessage":"ContextWindowExceededError: {exception_provider} - {message}","messagePattern":"ContextWindowExceededError: (.+?) - (.+?)","errorType":"exception","errorClass":"ContextWindowExceededError","httpStatus":400,"severity":"error","filePath":"litellm/litellm_core_utils/exception_mapping_utils.py","lineNumber":298,"sourceCode":"            \"openai.OpenAIError\",\n            f\"{custom_llm_provider}.{custom_llm_provider}Error\",\n        )\n    if custom_llm_provider == \"openai\":\n        exception_provider = \"OpenAI\" + \"Exception\"\n    else:\n        exception_provider = custom_llm_provider[0].upper() + custom_llm_provider[1:] + \"Exception\"\n\n    if ExceptionCheckers.is_error_str_rate_limit(\n        error_str, status_code=getattr(original_exception, \"status_code\", None)\n    ):\n        raise RateLimitError(\n            message=f\"RateLimitError: {exception_provider} - {message}\",\n            model=model,\n            llm_provider=custom_llm_provider,\n            response=getattr(original_exception, \"response\", None),\n        )\n    elif ExceptionCheckers.is_error_str_context_window_exceeded(error_str):\n        raise ContextWindowExceededError(\n            message=f\"ContextWindowExceededError: {exception_provider} - {message}\",\n            llm_provider=custom_llm_provider,\n            model=model,\n            response=getattr(original_exception, \"response\", None),\n            litellm_debug_info=extra_information,\n        )\n    elif \"invalid_request_error\" in error_str and \"model_not_found\" in error_str:\n        raise NotFoundError(\n            message=f\"{exception_provider} - {message}\",\n            llm_provider=custom_llm_provider,\n            model=model,\n            response=getattr(original_exception, \"response\", None),\n            litellm_debug_info=extra_information,\n        )\n    elif \"A timeout occurred\" in error_str:\n        raise Timeout(\n            message=f\"{exception_provider} - {message}\",\n            model=model,","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/exception_mapping_utils.py#L280-L316","documentation":"Normalized ContextWindowExceededError raised when the provider error string matches litellm's context-window heuristics (e.g. OpenAI's 'maximum context length is ... tokens, however you requested ...'). It signals the request's prompt (+ expected completion) exceeds the model's context window, not a transient failure — retrying unchanged will fail again.","triggerScenarios":"Sending a long conversation or large document to a model whose window is smaller than prompt+max_tokens; vision/file payloads inflating token counts; provider strings like 'context_length_exceeded' hitting the is_error_str_context_window_exceeded branch.","commonSituations":"Summarizing big PDFs/transcripts on an 8k model; unbounded chat histories growing past the window over a long session; setting max_tokens close to the window leaving no room for the prompt; model downgrades (to a smaller-context variant) without trimming inputs.","solutions":["Trim or compress the prompt: drop old turns, summarize history, or chunk the document and map/reduce.","Switch the request to a model with a larger context window (or a provider long-context variant).","Reduce max_tokens so prompt+completion fits, and count tokens before sending (litellm's token_counter) to fail fast client-side."],"exampleFix":"# before\nresp = litellm.completion(model=\"gpt-3.5-turbo\", messages=all_500k_tokens)\n# -> ContextWindowExceededError\n\n# after\nfrom litellm import token_counter\nmsgs = trim_to_budget(all_messages, budget=6000)  # custom trim\nassert token_counter(model=\"gpt-3.5-turbo\", messages=msgs) < 8000\nresp = litellm.completion(model=\"gpt-3.5-turbo\", messages=msgs, max_tokens=1000)","handlingStrategy":"validation","validationCode":"from litellm import token_counter\n\ndef fits_context(model: str, messages: list, max_tokens: int) -> bool:\n    limit = litellm.get_max_tokens(model) or 0\n    return token_counter(model=model, messages=messages) + max_tokens < limit\n\nif not fits_context(model, msgs, 1000):\n    msgs = trim_history(msgs, budget=4000)","typeGuard":"from litellm import ContextWindowExceededError\n\ndef is_context_window_error(exc: BaseException) -> bool:\n    return isinstance(exc, ContextWindowExceededError)","tryCatchPattern":"from litellm import ContextWindowExceededError\n\ntry:\n    resp = litellm.completion(model=m, messages=msgs)\nexcept ContextWindowExceededError:\n    msgs = summarize_history(msgs)          # shrink, then ONE retry — never loop unchanged\n    resp = litellm.completion(model=m, messages=msgs)","preventionTips":["Count tokens client-side before sending (litellm.token_counter).","Cap stored conversation history; summarize old turns on a schedule.","Keep prompt + max_tokens below the model's window with a safety margin."],"tags":["context-window","tokens","exception-mapping","provider-error"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}