What causes "{field_name} is required" in BerriAI/litellm?

Validate the field is present at the request boundary and return 400 before any URL building.

BerriAI/litellm · error · ValueError

is required

Error message

{field_name} is required

What it means

ValueError raised by encode_url_path_segment when the value to percent-encode into a URL path segment is None. This helper hardens user-controlled path segments (None, empty strings, and standalone '.'/'..' are all rejected) before they are appended to an upstream URL, so a missing required field fails fast instead of producing a malformed or traversable URL.

Solutions

Validate the field is present at the request boundary and return 400 before any URL building.
Use explicit presence checks instead of .get() with a None default feeding a URL builder.
Give the route a concrete, semantically valid default only when omission is legitimate.

Example fix

# before
key_id = request.get("key_id")  # None when omitted
path = encode_url_path_segment(key_id)  # ValueError: key_id is required

# after
key_id = request.get("key_id")
if not key_id:
    raise HTTPException(status_code=400, detail="key_id is required")
path = encode_url_path_segment(key_id, field_name="key_id")

Defensive patterns

Strategy: validation

Validate before calling

key_id = request.get("key_id")
if key_id is None:
    raise HTTPException(status_code=400, detail="key_id is required")
path = encode_url_path_segment(key_id, field_name="key_id")

Type guard

def is_present_path_segment(value: object) -> bool:
    return value is not None

Try / catch

try:
    path = encode_url_path_segment(value, field_name="key_id")
except ValueError as e:
    raise HTTPException(status_code=400, detail=str(e))

Prevention

Make path-forming fields required at the API schema level so None never reaches URL builders.
Never feed dict.get() results into URL construction without a presence check.

When it happens

Trigger: Calling encode_url_path_segment(None) directly, or an API that builds an upstream path from an optional field (key id, file id, team id) that the caller omitted — typically request.get('key_id') returning None and being passed straight through.

Common situations: Proxy routes that interpolate request-supplied ids into provider URLs (Gemini files, Bedrock agents, OpenAI containers, etc. all use this helper); optional path parameters with no boundary validation; None defaults leaking from config or env parsing.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at litellm/litellm_core_utils/url_utils.py:56

]

_ALLOWED_SCHEMES: Final = ("http", "https")


class SSRFError(ValueError):
    """Raised when a URL targets a blocked network."""


def encode_url_path_segment(value: Any, *, field_name: str = "path parameter") -> str:
    """Percent-encode one user-controlled URL path segment.

    ``urllib.parse.quote(..., safe="")`` intentionally leaves RFC 3986
    unreserved characters such as ``.`` unescaped, so reject standalone dot
    segments before they can be appended to an upstream URL and normalized by
    the HTTP client.
    """
    if value is None:
        raise ValueError(f"{field_name} is required")

    value_str: Final = str(value)
    if value_str == "":
        raise ValueError(f"{field_name} is required")
    if value_str in {".", ".."}:
        raise ValueError(f"{field_name} cannot be a dot path segment")

    return quote(value_str, safe="")


def encode_url_path_segments(value: Any, *, field_name: str = "path") -> str:
    """Percent-encode a user-controlled URL path made of multiple segments.

    Empty segments are rejected, so leading, trailing, or consecutive slashes
    fail closed instead of being normalized by the HTTP client.
    """
    if value is None:
        raise ValueError(f"{field_name} is required")

View on GitHub (pinned to 77b7c6c40c)