{"record":{"id":"338bd2ee08d874d9","repo":"BerriAI/litellm","slug":"field-name-is-required","errorCode":null,"errorMessage":"{field_name} is required","messagePattern":"(.+?) is required","errorType":"validation","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/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/url_utils.py#L38-L74","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","If the segment is legitimately optional, skip appending that path segment instead of passing None.","Provide a sensible non-empty default or reject the request with a 400-style error naming the missing field."],"exampleFix":"// before\nconst url = `${base}/${encodeUrlPathSegment(opts.model_id)}`; // model_id may be None\n\n# after (python caller)\nif not opts.get(\"model_id\"):\n    raise ValueError(\"model_id is required\")\nurl = f\"{base}/{encode_url_path_segment(opts['model_id'], field_name='model_id')}\"","handlingStrategy":"validation","validationCode":"def require_path_segment(value, field_name):\n    if value is None:\n        raise ValueError(f\"{field_name} is required\")\n    return value\n\nsegment = require_path_segment(params.get(\"file_id\"), \"file_id\")\nurl = f\"{base}/{encode_url_path_segment(segment, field_name='file_id')}\"","typeGuard":"def is_present_str(value) -> bool:\n    return value is not None and isinstance(value, str)","tryCatchPattern":"try:\n    url = f\"{base}/{encode_url_path_segment(segment, field_name='file_id')}\"\nexcept ValueError as e:\n    raise HTTPException(status_code=400, detail=str(e))","preventionTips":["Validate required path parameters at the API boundary before URL construction.","Never pass Optional fields directly into URL builders; resolve them first.","Include field_name when calling encode_url_path_segment so errors identify the missing field."],"tags":["url","validation","valueerror","path-segment"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}