{"record":{"id":"338bd2ee08d874d9","repo":"BerriAI/litellm","slug":"field-name-is-required","errorCode":null,"errorMessage":"{field_name} is required","messagePattern":"(.+?) is required","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/litellm_core_utils/url_utils.py","lineNumber":56,"sourceCode":"]\n\n_ALLOWED_SCHEMES: Final = (\"http\", \"https\")\n\n\nclass SSRFError(ValueError):\n    \"\"\"Raised when a URL targets a blocked network.\"\"\"\n\n\ndef encode_url_path_segment(value: Any, *, field_name: str = \"path parameter\") -> str:\n    \"\"\"Percent-encode one user-controlled URL path segment.\n\n    ``urllib.parse.quote(..., safe=\"\")`` intentionally leaves RFC 3986\n    unreserved characters such as ``.`` unescaped, so reject standalone dot\n    segments before they can be appended to an upstream URL and normalized by\n    the HTTP client.\n    \"\"\"\n    if value is None:\n        raise ValueError(f\"{field_name} is required\")\n\n    value_str: Final = str(value)\n    if value_str == \"\":\n        raise ValueError(f\"{field_name} is required\")\n    if value_str in {\".\", \"..\"}:\n        raise ValueError(f\"{field_name} cannot be a dot path segment\")\n\n    return quote(value_str, safe=\"\")\n\n\ndef encode_url_path_segments(value: Any, *, field_name: str = \"path\") -> str:\n    \"\"\"Percent-encode a user-controlled URL path made of multiple segments.\n\n    Empty segments are rejected, so leading, trailing, or consecutive slashes\n    fail closed instead of being normalized by the HTTP client.\n    \"\"\"\n    if value is None:\n        raise ValueError(f\"{field_name} is required\")","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/litellm_core_utils/url_utils.py#L38-L74","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nkey_id = request.get(\"key_id\")  # None when omitted\npath = encode_url_path_segment(key_id)  # ValueError: key_id is required\n\n# after\nkey_id = request.get(\"key_id\")\nif not key_id:\n    raise HTTPException(status_code=400, detail=\"key_id is required\")\npath = encode_url_path_segment(key_id, field_name=\"key_id\")","handlingStrategy":"validation","validationCode":"key_id = request.get(\"key_id\")\nif key_id is None:\n    raise HTTPException(status_code=400, detail=\"key_id is required\")\npath = encode_url_path_segment(key_id, field_name=\"key_id\")","typeGuard":"def is_present_path_segment(value: object) -> bool:\n    return value is not None","tryCatchPattern":"try:\n    path = encode_url_path_segment(value, field_name=\"key_id\")\nexcept ValueError as e:\n    raise HTTPException(status_code=400, detail=str(e))","preventionTips":["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."],"tags":["url-encoding","path-segment","input-validation","valueerror"],"backgroundTag":"missing-required-argument","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}