{"record":{"id":"fad6aa11ba39375c","repo":"BerriAI/litellm","slug":"a2a-sdk-is-required-for-localhost-retry-handling","errorCode":null,"errorMessage":"A2A SDK is required for localhost retry handling. Install it with: pip install a2a-sdk","messagePattern":"A2A SDK is required for localhost retry handling\\. Install it with: pip install a2a-sdk","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"litellm/a2a_protocol/exception_mapping_utils.py","lineNumber":185,"sourceCode":"    Handle A2ALocalhostURLError by fixing the URL and creating a new client.\n\n    This is called when we catch an A2ALocalhostURLError and want to retry\n    with the corrected URL.\n\n    Args:\n        error: The localhost URL error\n        agent_card: The agent card object to fix\n        a2a_client: The current A2A client\n        is_streaming: Whether this is a streaming request (for logging)\n\n    Returns:\n        A new A2A client with the fixed URL\n\n    Raises:\n        ImportError: If the A2A SDK is not installed\n    \"\"\"\n    if not A2A_SDK_AVAILABLE:\n        raise ImportError(\"A2A SDK is required for localhost retry handling. Install it with: pip install a2a-sdk\")\n\n    if agent_card is None:\n        raise RuntimeError(\n            \"Cannot retry A2A localhost URL fix: no agent card is available to \"\n            \"rewrite, so the upstream URL cannot be corrected.\"\n        )\n\n    request_type: Final = \"streaming \" if is_streaming else \"\"\n    verbose_logger.warning(\n        \"A2A %srequest to '%s' failed: %s. Agent card contains localhost/internal URL. Retrying with base_url '%s'.\",\n        request_type,\n        error.localhost_url,\n        error.original_error,\n        error.base_url,\n    )\n\n    # Fix the agent card URL\n    set_agent_card_url(agent_card, error.base_url)","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/a2a_protocol/exception_mapping_utils.py#L167-L203","documentation":"Retrying a failed A2A request whose agent card advertised a localhost URL requires rebuilding the client through the a2a-sdk, so handle_a2a_localhost_retry raises ImportError when the SDK is not importable (A2A_SDK_AVAILABLE is False). In a healthy install you rarely reach it because client creation fails earlier without the SDK; hitting it usually means a broken, partial, or version-drifted a2a-sdk install.","triggerScenarios":"A localhost-URL retry is attempted on a host where 'import a2a' (or its compat layer) fails: SDK uninstalled after the client was built, a corrupted venv, or an a2a-sdk version that imports but lacks the pieces litellm expects.","commonSituations":"Slim production images omitting a2a-sdk; dependency downgrades removing the package mid-session; litellm and a2a-sdk versions drifting apart after a partial upgrade.","solutions":["pip install a2a-sdk (or pip install 'litellm[extra_proxy]', which pins a2a-sdk>=1.1.0,<2.0) and restart the worker","Verify: python -c \"import a2a; print(a2a.__version__)\"","If the package is present but still failing, force-reinstall to repair a broken install: pip install --force-reinstall 'a2a-sdk>=1.1.0,<2.0'"],"exampleFix":"# before\npip install litellm  # a2a-sdk missing -> retry path dies with ImportError\n\n# after\npip install 'litellm[extra_proxy]'  # includes a2a-sdk>=1.1.0,<2.0","handlingStrategy":"try-catch","validationCode":"def a2a_sdk_available() -> bool:\n    try:\n        import a2a  # noqa: F401\n        from a2a.compat.v0_3 import conversions  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\n\nassert a2a_sdk_available(), 'pip install a2a-sdk before using A2A retries'","typeGuard":null,"tryCatchPattern":"try:\n    resp = await asend_message(a2a_client=client, request=req)\nexcept ImportError as e:\n    if 'a2a-sdk' in str(e):\n        raise SystemExit('Install a2a-sdk (litellm[extra_proxy]) to use A2A') from e\n    raise","preventionTips":["Install litellm[extra_proxy] wherever A2A routes are enabled","Run python -c \"from a2a.compat.v0_3 import conversions\" in your deployment smoke test","Pin a2a-sdk>=1.1.0,<2.0 explicitly to match litellm's constraint"],"tags":["a2a","dependency","import-error","retry"],"backgroundTag":"missing-optional-dependency","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}