BerriAI/litellm · error · APIConnectionError

\n

Error message

{original_exception}\n{_redact_string(traceback.format_exc())}

What it means

Companion branch for unmapped exceptions WITHOUT a request attribute: exception_type() raises APIConnectionError whose message embeds str(original_exception) plus a redacted traceback, and stubs the request as POST https://api.openai.com/v1/ (marked 'stub' in code). The traceback is included because for arbitrary exceptions it is the only way to diagnose the real cause (litellm#4201).

Solutions

  1. Read the embedded traceback in the message — it pinpoints the file/line of the real failure, which is rarely a network issue despite the exception class.
  2. Reproduce outside litellm with the provider SDK directly using the same parameters.
  3. Upgrade or pin litellm and the provider SDK to a known-compatible pair.
  4. Report to litellm with the traceback so the exception class gets a dedicated mapping.

Example fix

# before
litellm.completion(model="<provider>/<model>", messages=msgs)

# after
try:
    litellm.completion(model="<provider>/<model>", messages=msgs)
except litellm.APIConnectionError as e:
    log.error("unmapped failure w/ traceback: %s", e)  # traceback is inside the message
    raise
Defensive patterns

Strategy: try-catch

Try / catch

try:
    resp = litellm.completion(**kwargs)
except litellm.APIConnectionError as e:
    if "Traceback (most recent call last)" in str(e):
        # unmapped non-HTTP failure; traceback inside message is the real signal
        capture_exception(e)  # ship to Sentry, etc.
    raise

Prevention

When it happens

Trigger: Any exception escaping a provider call that litellm doesn't recognize and that lacks .request — e.g. KeyError/TypeError inside a provider adapter, parsing failures of response bodies, or non-HTTP library bugs. The redacted traceback in the message shows the true origin.

Common situations: litellm/provider SDK version mismatches producing TypeErrors; malformed streaming chunks breaking parsers; custom callback hooks raising; bugs in newly released provider integrations.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/557b46981f62b818. Report an issue: GitHub.

Appendix: source

Thrown at litellm/litellm_core_utils/exception_mapping_utils.py:2485

                message=f"{exception_provider} BadRequestError : This can happen due to missing AZURE_API_VERSION: {original_exception}",
                model=model,
                llm_provider=custom_llm_provider,
                response=getattr(original_exception, "response", None),
            )
        else:  # ensure generic errors always return APIConnectionError=
            """
            For unmapped exceptions - raise the exception with traceback - https://github.com/BerriAI/litellm/issues/4201
            """
            exception_mapping_worked = True
            if hasattr(original_exception, "request"):
                raise APIConnectionError(
                    message=f"{exception_provider} - {error_str}",
                    llm_provider=custom_llm_provider,
                    model=model,
                    request=getattr(original_exception, "request", None),
                )
            else:
                raise APIConnectionError(
                    message=f"{original_exception}\n{_redact_string(traceback.format_exc())}",
                    llm_provider=custom_llm_provider,
                    model=model,
                    request=httpx.Request(method="POST", url="https://api.openai.com/v1/"),  # stub the request
                )
    except Exception as e:
        # LOGGING
        exception_logging(
            logger_fn=None,
            additional_args={
                "exception_mapping_worked": exception_mapping_worked,
                "original_exception": original_exception,
            },
            exception=e,
        )

        # don't let an error with mapping interrupt the user from receiving an error from the llm api calls
        if exception_mapping_worked:

View on GitHub (pinned to 77b7c6c40c)