openai/openai-python · error · ValueError

Constructed path {path_result!r} contains dot-segment {segme

Error message

Constructed path {path_result!r} contains dot-segment {segment!r} which is not allowed

What it means

After interpolating a URL path template, the SDK validates that no single slash-delimited segment is a dot-segment ('.', '..', or percent-encoded equivalents). This ValueError protects against path-traversal-style constructed URLs: interpolated values that are '..' (or that concatenate with static text to form '.') could make the request escape the intended resource path. It fires client-side before any network request is made.

Source

Thrown at src/openai/_utils/_path.py:119

    rest = template
    if "#" in rest:
        rest, fragment_template = rest.split("#", 1)
    if "?" in rest:
        rest, query_template = rest.split("?", 1)
    path_template = rest

    # Interpolate each portion with the appropriate quoting rules.
    path_result = _interpolate(path_template, kwargs, _quote_path_segment_part)

    # Reject dot-segments (. and ..) in the final assembled path.  The check
    # runs after interpolation so that adjacent placeholders or a mix of static
    # text and placeholders that together form a dot-segment are caught.
    # Also reject percent-encoded dot-segments to protect against incorrectly
    # implemented normalization in servers/proxies.
    for segment in path_result.split("/"):
        if _DOT_SEGMENT_RE.match(segment):
            raise ValueError(f"Constructed path {path_result!r} contains dot-segment {segment!r} which is not allowed")

    result = path_result
    if query_template is not None:
        result += "?" + _interpolate(query_template, kwargs, _quote_query_part)
    if fragment_template is not None:
        result += "#" + _interpolate(fragment_template, kwargs, _quote_fragment_part)

    return result

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Reject or sanitize user-supplied path parameters: strip leading dots and reject '..' before calling the API
2. Validate ids against an expected pattern (e.g. ^[A-Za-z0-9_-]+$) before passing them
3. URL-encode path parameters through the SDK's supported mechanisms instead of manual string building
4. Return a 400 to your own caller when an invalid id is detected rather than attempting the request

Example fix

# before
client.things.get(thing_id=user_input)  # user_input = '..'

# after
import re
if not re.fullmatch(r"[A-Za-z0-9_-]+", user_input):
    raise ValueError("invalid id")
client.things.get(thing_id=user_input)

import re
DOT = re.compile(r"^(\.|%2e|%2E)+$")
if any(DOT.fullmatch(seg) or seg in (".", "..") for seg in value.split("/")):
    raise ValueError("unsafe id")

import re
SAFE_ID = re.compile(r"^[A-Za-z0-9_-]+$")
def is_safe_path_id(v: str) -> bool: return bool(SAFE_ID.fullmatch(v))

try:
    client.things.get(thing_id=rid)
except ValueError as e:
    return HTTPException(400, "invalid identifier")

When it happens

Trigger: Passing an id/path parameter equal to '..', '.', '%2e%2e', or a value that combined with adjacent template text forms a dot-segment, e.g. id='.x'/value where 'foo/{id}' yields a segment starting with a dot matching the DOT_SEGMENT regex; also test-driven checks of the validation itself.

Common situations: Using user-supplied or filesystem-derived identifiers verbatim as path params; sanitizing or truncating ids in a way that leaves '.' or '..'; migrating code that previously joined path components manually.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• Pagination is only supported with mappings
• The `default_headers` and `set_default_headers` arguments ar
• The `default_query` and `set_default_query` arguments are mu
• invalid datetime format
• invalid date format

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/29284f273b218fe6. Report an issue: GitHub.