BerriAI/litellm · error · ImportError

A2A SDK is required for localhost retry handling. Install it

Error message

A2A SDK is required for localhost retry handling. Install it with: pip install a2a-sdk

What it means

Error "A2A SDK is required for localhost retry handling. Install it with: pip install a2a-sdk" thrown in BerriAI/litellm.

Source

Thrown at litellm/a2a_protocol/exception_mapping_utils.py:185

    Handle A2ALocalhostURLError by fixing the URL and creating a new client.

    This is called when we catch an A2ALocalhostURLError and want to retry
    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)

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Install the A2A SDK: pip install a2a-sdk.

When it happens

Trigger: Thrown at litellm/a2a_protocol/exception_mapping_utils.py:185 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/fad6aa11ba39375c. Report an issue: GitHub.