BerriAI/litellm · error · ValueError

{field_name} is required

Error message

{field_name} is required

What it means

Thrown by encode_url_path_segment in litellm's URL utilities when the value to be percent-encoded into a URL path segment is None. This helper exists to safely build upstream URLs from user-controlled path parameters, and it fails closed on missing input rather than silently producing a malformed URL. It is a plain ValueError, so it indicates a caller bug (a None was passed where a path segment was required), not a network or configuration problem.

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 6c2dcb801b)

Solutions

1. Check the caller of encode_url_path_segment and ensure the value passed for the field named in the message is set before URL construction (fail fast at the request-validation layer).
2. If the segment is legitimately optional, skip appending that path segment instead of passing None.
3. Provide a sensible non-empty default or reject the request with a 400-style error naming the missing field.

Example fix

// before
const url = `${base}/${encodeUrlPathSegment(opts.model_id)}`; // model_id may be None

# after (python caller)
if not opts.get("model_id"):
    raise ValueError("model_id is required")
url = f"{base}/{encode_url_path_segment(opts['model_id'], field_name='model_id')}"

def require_path_segment(value, field_name):
    if value is None:
        raise ValueError(f"{field_name} is required")
    return value

segment = require_path_segment(params.get("file_id"), "file_id")
url = f"{base}/{encode_url_path_segment(segment, field_name='file_id')}"

def is_present_str(value) -> bool:
    return value is not None and isinstance(value, str)

try:
    url = f"{base}/{encode_url_path_segment(segment, field_name='file_id')}"
except ValueError as e:
    raise HTTPException(status_code=400, detail=str(e))

When it happens

Trigger: Calling encode_url_path_segment(None) or any wrapper (e.g. encode_url_path_segments) that forwards a None path parameter — typically when a caller builds a URL from an optional field (model id, file id, key) that was never set, e.g. encode_url_path_segment(request.model_id, field_name="model_id") where model_id is None.

Common situations: Passing an unset/optional litellm_params field into a URL-building path; a provider transformation handler receiving None for a template variable; deserialized config where a path field was omitted; refactors that made a previously-required argument Optional.

Related errors

• prompt_id is required for Arize Phoenix prompt manager
• {field_name} cannot be a dot path segment
• URL scheme '{parsed.scheme}' is not allowed
• URL has no hostname
• Invalid mode: {custom_auth_settings['mode']}

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