BerriAI/litellm · error · HTTPException

litellm_params.api_base must contain a valid hostname

Error message

litellm_params.api_base must contain a valid hostname

What it means

Raised in the generic-guardrail registration handler when the parsed api_base has no hostname (e.g. 'https:///path' or a scheme-only string). The guardrail needs a reachable host to POST hooks to; this is the hostname stage of the api_base validation ladder that checks presence, then scheme, then hostname, then mode.

Source

Thrown at litellm/proxy/guardrails/guardrail_endpoints.py:741

    if params.get("guardrail") != GENERIC_GUARDRAIL_API:
        raise HTTPException(
            status_code=400,
            detail=f"Only guardrails with litellm_params.guardrail={GENERIC_GUARDRAIL_API!r} are accepted for registration",
        )
    api_base: Final = params.get("api_base")
    if not api_base:
        raise HTTPException(
            status_code=400,
            detail="litellm_params.api_base is required for generic_guardrail_api",
        )
    parsed: Final = urlparse(api_base)
    if parsed.scheme not in ("http", "https"):
        raise HTTPException(
            status_code=400,
            detail="litellm_params.api_base must use http or https scheme",
        )
    if not parsed.hostname:
        raise HTTPException(
            status_code=400,
            detail="litellm_params.api_base must contain a valid hostname",
        )
    mode: Final = params.get("mode")
    if mode is None:
        raise HTTPException(
            status_code=400,
            detail="litellm_params.mode is required (e.g. pre_call, post_call)",
        )

    try:
        existing = await _guardrails_table(prisma_client).find_unique(where={"guardrail_name": request.guardrail_name})
        if existing is not None:
            raise HTTPException(
                status_code=400,
                detail=f"Guardrail with name {request.guardrail_name!r} already exists",
            )
    except HTTPException:

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Provide an api_base that includes a valid hostname.

Example fix

api_base: https://guardrail.example.com/v1

When it happens

Trigger: Thrown at litellm/proxy/guardrails/guardrail_endpoints.py:741 when the library encounters an invalid state.

Common situations: The guardrail api_base URL lacks a hostname.

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