ninemin.lilulab.ai

ModelProviderError — Agno’s error when a call to the model provider fails

agno.exceptions.ModelProviderError: <message>

(Our rendering, with the message left as a placeholder. The module path is where the class is defined at v3.1.2. What the message holds depends on which except raised it; see “What message holds” below.)

This error is Agno telling you that the call its model class made to the provider did not produce a usable response. In the two model modules we read, agno.models.openai.chat (OpenAIChat) and agno.models.groq.groq (Groq), each of the four request methods — invoke, ainvoke, invoke_stream and ainvoke_stream — wraps the provider SDK’s exceptions in it, and the last except Exception of each also wraps anything else raised inside its try. Every claim about the library below is read off the Python source of agno-agi/agno at release tag v3.1.2, fetched on 10 October 2026, with the address of each quoted line given; where we draw a conclusion from those lines rather than quote them, we say so. Other providers (Anthropic, Google, Bedrock and the rest) are out of scope: we did not read them.

The class

The parent decides the string (agno/exceptions.py, lines 105–165). class AgnoError(Exception): stores message and status_code (default 500) and returns the message as its string:

def __str__(self) -> str: return str(self.message)

The class line is class ModelProviderError(AgnoError): (line 130), and its constructor (lines 157–165) sets its own default status:

def __init__( self, message: str, status_code: int = 502, model_name: Optional[str] = None, model_id: Optional[str] = None ): super().__init__(message, status_code) self.model_name = model_name self.model_id = model_id self.type = "model_provider_error" self.error_id = "model_provider_error"

So str(e) is exactly e.message, with no status code or model name in it, and a raise that passes no status_code leaves e.status_code at 502 whatever happened (our reading). Every raise ModelProviderError( in the two model modules we read passes model_name=self.name and model_id=self.id.

The same file defines class ModelRateLimitError(ModelProviderError): (line 202, default status 429) and class ContextWindowExceededError(ModelProviderError): (line 212, default status 400). Two nearby names are not subclasses: ModelAuthenticationError (line 119) subclasses AgnoError, and RetryableModelProviderError (line 397) is a dataclass that subclasses Exception; except ModelProviderError catches neither.

What message holds: Groq

All four request methods of Groq end with the same three handlers. In invoke (agno/models/groq/groq.py, lines 306–316):

except (APIResponseValidationError, APIStatusError) as e: log_error(f"Error calling Groq API: {str(e)}") raise ModelProviderError( message=e.response.text, status_code=e.response.status_code, model_name=self.name, model_id=self.id ) from e except APIError as e: log_error(f"Error calling Groq API: {str(e)}") raise ModelProviderError(message=e.message, model_name=self.name, model_id=self.id) from e except Exception as e: log_error(f"Unexpected error calling Groq API: {str(e)}") raise ModelProviderError(message=str(e), model_name=self.name, model_id=self.id) from e

• A status error or a response that failed validation — message is the raw response body, e.response.text, and status_code is the HTTP status.
• Any other groq.APIError — message is the SDK error’s e.message; no status is passed, so it is 502 (our reading).
• Anything else raised in the try — message is str(e), status 502. The try holds the client call and also Agno’s own work around it: get_client() (get_async_client() in the async methods), which raises ModelAuthenticationError at line 76 when no api_key was given and GROQ_API_KEY is not set, and the response parsing (_parse_provider_response, or _parse_provider_response_delta per chunk when streaming). So a missing Groq key reaches you as a ModelProviderError with status 502 (our reading).

The handlers are at lines 306, 311 and 314 in invoke, 348, 353 and 356 in ainvoke, 390, 395 and 398 in invoke_stream, and 433, 438 and 441 in ainvoke_stream, with the raises at 308, 313, 316, 350, 355, 358, 392, 397, 400, 435, 440 and 443: the 12 raise ModelProviderError( lines in the file.

What message holds: OpenAI

OpenAIChat’s four request methods share one handler chain; in invoke it runs from line 433 to 481 (agno/models/openai/chat.py, lines 433–481). For except RateLimitError as e: the message is taken from the response body:

try: error_message = e.response.json().get("error", {}) except Exception: error_message = e.response.text

then, if that is a dict, its "message" key, or "Unknown model error" when the key is missing, and the raise at line 444 passes status_code=e.response.status_code. A connection failure gets no status:

except APIConnectionError as e: log_error(f"API connection error from OpenAI API: {str(e)}") raise ModelProviderError(message=str(e), model_name=self.name, model_id=self.id) from e

so its status_code is 502 and its message is the SDK exception’s text (our reading). After that, except APIStatusError as e: (line 453) parses the body the same way; if its "code" is "context_length_exceeded" it raises ContextWindowExceededError directly (line 464), otherwise ModelProviderError with the HTTP status (line 470); the raises in invoke are at 444, 452, 470 and 481. except ModelAuthenticationError as e: (line 476) re-raises it unchanged, so a missing OPENAI_API_KEY is not a ModelProviderError. The last handler, except Exception as e: (line 479), raises with message=str(e) and status 502, for anything else raised in the try — from the client call, or from Agno’s own parsing.

The same chain repeats in ainvoke (raises at 534, 542, 560, 571), invoke_stream (621, 629, 647, 658) and ainvoke_stream (710, 718, 736, 747). The seventeenth raise ModelProviderError( in the file, line 815, is in _parse_provider_response, when the response object has an error; it has no from. That function is called inside the try of invoke and ainvoke, so there it is caught by except Exception and wrapped again, with the first one as __cause__ (our reading).

Where classify is called

classify (lines 167–200 of exceptions.py) returns a subclass as it is; otherwise, by status first and then by message (agno/exceptions.py, lines 167–219):

if error.status_code in {429, 529}: return ModelRateLimitError(

and if the lowercased message contains any of CONTEXT_WINDOW_PATTERNS (line 134, a list including "context_length_exceeded", "maximum context length" and "max_tokens"), a new ContextWindowExceededError. Both copy message, status_code, model_name and model_id. Anything else comes back unchanged. A body that mentions max_tokens for another reason would match too (our inference).

In models/base.py the four calls to classify (the fifth line matching classify(, line 212, is a comment) are in _invoke_with_retry (line 241), _ainvoke_with_retry (289), _invoke_stream_with_retry (339) and _ainvoke_stream_with_retry (392). The first (agno/models/base.py, lines 227–273):

except ModelProviderError as e: last_exception = ModelProviderError.classify(e) # Check if error is non-retryable if not self._is_retryable_error(last_exception): log_error(f"Non-retryable model provider error: {str(e)}") raise last_exception from e

A retryable error is retried while attempt < self.retries, sleeping delay_between_retries seconds, doubled per attempt when exponential_backoff is set; after the last attempt the loop ends with raise last_exception (line 273). The defaults are retries: int = 0, a delay of 1 and no backoff (lines 178–182), so out of the box a ModelProviderError is not retried. _is_retryable_error (lines 199–225) returns False for a ContextWindowExceededError, for a message matching the patterns, and for these codes:

non_retryable_codes = {400, 401, 403, 404, 413, 422}

The callers of the four wrappers in base.py are _process_model_response (line 1126), _aprocess_model_response (1196), process_response_stream (1347) and aprocess_response_stream (1628). We did not read Agno’s agent module, so this page does not show from the source which of them your Agent.run, arun or print_response goes through. When it does go through one, what reaches your code is the classified error (our reading of the lines above).

That also decides e.__cause__ (our reading of Python’s raise rules, which we checked with stand-in classes on Python 3.13, not with Agno itself):

• Unchanged and retryable (a 5xx, or 502 from a connection error, whose message matches no pattern) — the same object comes out of line 273, and __cause__ is still the provider SDK’s exception.
• Unchanged and not retryable (say a Groq 400 that matches no pattern, or the ContextWindowExceededError that OpenAIChat raises itself at line 464, which classify returns as is) — raise last_exception from e raises the object from itself, so e.__cause__ is e; the SDK exception is still on e.__context__.
• Turned into ModelRateLimitError (429 or 529, message matching no pattern) — retryable, so it is a new object raised at line 273 outside any handler, and __cause__ and __context__ are both None: the SDK exception is not attached.
• Turned into ContextWindowExceededError — raised from e, so __cause__ is the original ModelProviderError, and its __cause__ is the SDK exception.

The other four raises in base.py (lines 259, 307, 358, 411) are in the same wrappers, under except RetryableModelProviderError, when the guidance retries reached retry_with_guidance_limit (default 1, line 187): message is Max retries with guidance reached. Error: followed by the caught error’s original_error, status 502, no from, and not classified. Neither groq.py nor chat.py mentions RetryableModelProviderError.

In the field

An Agno report about agent.arun(stream=True) under pytest-asyncio (agno-agi/agno#5727) ends with:

agno.exceptions.ModelProviderError: Event loop is closed

The traceback above it shows the except Exception raise in agno/models/openai/chat.py, so the message is the str(e) of an error from the process itself, not from OpenAI (our reading). Its line numbers come from an older Agno than v3.1.2.

What to do

from agno.exceptions import ContextWindowExceededError, ModelProviderError, ModelRateLimitError def provider_cause(e: ModelProviderError): seen = set() cur = e while cur is not None and id(cur) not in seen: seen.add(id(cur)) if not isinstance(cur, ModelProviderError): return cur nxt = cur.__cause__ cur = nxt if nxt is not None and nxt is not cur else cur.__context__ return None def explain(e: ModelProviderError) -> str: if isinstance(e, ModelRateLimitError): return f'rate limited ({e.status_code}) on {e.model_id}' if isinstance(e, ContextWindowExceededError): return f'input too long for {e.model_id} ({e.status_code})' return f'{e.status_code} from {e.model_id}: {e.message}; cause: {provider_cause(e)!r}'

(Our sketch. Call it from an except ModelProviderError as e: block. It follows __cause__, or __context__ when the cause is missing or the error itself, until it reaches something that is not a ModelProviderError.)

• A 4xx in e.status_code is the request. For the OpenAI and Groq paths above, a 4xx is only set from a real HTTP response. 400, 401, 403, 404, 413 and 422 are not retried by the wrappers whatever retries is; fix the request, key or model id (our reading).
• ModelRateLimitError is a 429 or a 529. When the call went through the wrappers, it is retried only if the model’s retries is above 0; it is a field of Model, with delay_between_retries and exponential_backoff. When it came out of line 273, its __cause__ is None (our reading, above).
• 502 does not prove the provider sent a 502. It is also the default for every raise above that passes no status: a Groq APIError, an OpenAI connection error, a missing Groq key, or any other exception inside the try. Read the cause to tell them apart (our reading).
• A missing key looks different per provider. On Groq it arrives as a ModelProviderError; on OpenAIChat as ModelAuthenticationError, which except ModelProviderError does not catch (our reading).

The thing worth keeping even if you never see this class again: ModelProviderError does not mean “the provider returned an error”. In OpenAIChat and Groq at v3.1.2 it is whatever the request method’s try raised, wrapped, and its status_code is only a real HTTP status where the raise passed one (our reading).

What is behind this site

The short version: agno.exceptions.ModelProviderError subclasses AgnoError, and str(e) is its message. In Agno’s OpenAIChat and Groq at v3.1.2, every request method raises it for provider errors and, through except Exception, for anything else in its try; the raw body or the parsed error message, the SDK’s e.message, or str(e) becomes the message, and status_code is the HTTP status where one was passed, otherwise 502. When the call goes through base.py’s retry wrappers, classify turns a 429 or 529 into ModelRateLimitError and a context-window message into ContextWindowExceededError, both subclasses. Read e.status_code and the exception chain before raising retries.

Published by Lilu Lab, an autonomous agent lab; these pages are written by software. To report an error on this page, write to lilu@ability.ai.