BerriAI/litellm · error · RuntimeError

Cannot retry A2A localhost URL fix: no agent card is availab

Error message

Cannot retry A2A localhost URL fix: no agent card is available to rewrite, so the upstream URL cannot be corrected.

What it means

Error "Cannot retry A2A localhost URL fix: no agent card is available to rewrite, so the upstream URL cannot be corrected." thrown in BerriAI/litellm.

Source

Thrown at litellm/a2a_protocol/exception_mapping_utils.py:188

    with the corrected URL.

    Args:
        error: The localhost URL error
        agent_card: The agent card object to fix
        a2a_client: The current A2A client
        is_streaming: Whether this is a streaming request (for logging)

    Returns:
        A new A2A client with the fixed URL

    Raises:
        ImportError: If the A2A SDK is not installed
    """
    if not A2A_SDK_AVAILABLE:
        raise ImportError("A2A SDK is required for localhost retry handling. Install it with: pip install a2a-sdk")

    if agent_card is None:
        raise RuntimeError(
            "Cannot retry A2A localhost URL fix: no agent card is available to "
            "rewrite, so the upstream URL cannot be corrected."
        )

    request_type: Final = "streaming " if is_streaming else ""
    verbose_logger.warning(
        "A2A %srequest to '%s' failed: %s. Agent card contains localhost/internal URL. Retrying with base_url '%s'.",
        request_type,
        error.localhost_url,
        error.original_error,
        error.base_url,
    )

    # Fix the agent card URL
    set_agent_card_url(agent_card, error.base_url)

    # Reuse the httpx client and call context LiteLLM attached at creation, since the
    # context carries this agent's trace-id/auth headers. Only clients built by

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Fetch the agent card first (or create the client via create_a2a_client) so the localhost URL can be rewritten before retrying.

When it happens

Trigger: Thrown at litellm/a2a_protocol/exception_mapping_utils.py:188 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/b47c556bb64935c6. Report an issue: GitHub.