BerriAI/litellm · error · AgentCardDiscoveryError

base_url is required

Error message

base_url is required

What it means

Guard inside fetch_well_known_card rejecting a call with a falsy base_url. The discovery function accepts keyword-only arguments and strategy flags, and this is the cheap pre-flight check before any HTTP attempt: with no base URL there is nothing to fetch .well-known agent cards from, so it fails fast with ValueError rather than a confusing URL-join error.

Source

Thrown at litellm/proxy/a2a/discovery.py:100

async def fetch_well_known_card(
    base_url: str,
    *,
    discovery_mode: DiscoveryMode = DiscoveryMode.WELL_KNOWN_FALLBACK,
    params: dict[str, Any] | None = None,
    timeout: float = DEFAULT_DISCOVERY_TIMEOUT_SECONDS,
    headers: dict[str, str] | None = None,
) -> dict[str, Any]:
    """
    Fetch an agent card from ``base_url`` using the strategy chosen by
    ``discovery_mode``. Returns the parsed JSON from the first path that
    responds with a JSON body.

    Raises:
        AgentCardDiscoveryError: if every path fails (network error, non-2xx,
            or non-JSON body), or if the chosen mode is missing required params.
    """
    if not base_url:
        raise AgentCardDiscoveryError("base_url is required")

    normalized: Final = _normalize_base_url(base_url)
    paths: Final = _paths_for_mode(discovery_mode, params)
    client: Final = get_async_httpx_client(
        llm_provider=httpxSpecialProvider.A2A,
        params={"timeout": timeout},
    )

    last_error: str | None = None
    for path in paths:
        url = f"{normalized}{path}"
        try:
            # ``async_safe_get`` validates the URL against the SSRF blocklist
            # (private/loopback IPs, cloud metadata endpoints, etc.) on every
            # redirect hop. Even though the discovery endpoint is admin-only,
            # we don't want a compromised admin key to be able to probe
            # internal infrastructure through this fetcher.
            # Pass ``headers or {}`` because ``async_safe_get`` (in the

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Provide base_url for the agent discovery request.

Example fix

base_url='https://agent.example.com'

When it happens

Trigger: Thrown at litellm/proxy/a2a/discovery.py:100 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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