{"record":{"id":"5cdcbc6bd31d37f5","repo":"BerriAI/litellm","slug":"field-name-cannot-be-a-dot-path-segment","errorCode":null,"errorMessage":"{field_name} cannot be a dot path segment","messagePattern":"(.+?) cannot be a dot path segment","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/litellm_core_utils/url_utils.py","lineNumber":62,"sourceCode":"    \"\"\"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\")\n\n    value_str: Final = str(value)\n    if value_str == \"\":\n        raise ValueError(f\"{field_name} is required\")\n\n    encoded_segments: Final = []","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/url_utils.py#L44-L80","documentation":"Thrown by encode_url_path_segment when the value is exactly \".\" or \"..\". urllib.parse.quote(..., safe=\"\") deliberately leaves RFC 3986 unreserved characters like '.' unescaped, so a literal dot segment would survive encoding and later be path-normalized by the HTTP client — enabling path traversal (e.g. escaping an intended URL prefix). litellm rejects dot segments outright as part of its SSRF/path-traversal hardening.","triggerScenarios":"Passing a user-controlled id/name that equals \".\" or \"..\" into a URL path builder — e.g. encode_url_path_segment(\"..\", field_name=\"file_id\"), or an encode_url_path_segments(\"files/../admin\") call where one split segment is a dot segment.","commonSituations":"Path traversal attempts or fuzzed input reaching a URL-building layer; file/blob id fields that accept arbitrary strings; copying S3-style key paths into segment builders without validating each component.","solutions":["Reject or sanitize user-supplied path components before URL construction: allow only a safe charset (e.g. [A-Za-z0-9_-]+) for ids destined for path segments.","If traversal-style keys are legitimate, percent-encode the slashes and dots yourself at a higher layer or pass the key as a query parameter instead.","Return a 400 to the client naming the invalid field instead of letting the ValueError propagate."],"exampleFix":"# before\nurl = f\"{base}/files/{encode_url_path_segment(file_id, field_name='file_id')}\"\n\n# after\nimport re\nif not re.fullmatch(r\"[A-Za-z0-9_-]+\", file_id or \"\"):\n    raise HTTPException(400, \"file_id contains illegal characters\")\nurl = f\"{base}/files/{encode_url_path_segment(file_id, field_name='file_id')}\"","handlingStrategy":"validation","validationCode":"import re\n\ndef is_safe_path_segment(value) -> bool:\n    return bool(isinstance(value, str) and re.fullmatch(r\"[^/\\\\]+\", value) and value not in {\".\", \"..\"})","typeGuard":"def is_safe_path_segment(value) -> bool:\n    return isinstance(value, str) and value not in {\"\", \".\", \"..\"} and \"/\" not in value","tryCatchPattern":"try:\n    encoded = encode_url_path_segment(value, field_name=\"file_id\")\nexcept ValueError:\n    return bad_request(\"file_id contains illegal path characters\")","preventionTips":["Allowlist a charset (e.g. [A-Za-z0-9_-]) for user-supplied URL path components.","Treat dot-segment rejection as expected behavior and map it to a 400, not a 500.","Never assemble URLs by string concatenation of raw user input; always go through the encoder."],"tags":["url","path-traversal","security","ssrf","validation"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}