HKUDS/Vibe-Trading · error · ValueError

path must start with "/"

Error message

path must start with "/"

What it means

Raised by the WebSocketConfig field validator for path when the HTTP/WebSocket upgrade path does not start with '/'. URL paths must begin with a slash to be routable (e.g. '/ws'); the validator normalizes and stores the path via _normalize_config_path after this check.

Source

Thrown at agent/src/channels/websocket.py:112

    @field_validator("unix_socket_path")
    @classmethod
    def unix_socket_path_format(cls, value: str) -> str:
        value = value.strip()
        if not value:
            return ""
        if "\x00" in value:
            raise ValueError("unix_socket_path must not contain NUL bytes")
        path = Path(value).expanduser()
        if not path.is_absolute():
            raise ValueError("unix_socket_path must be an absolute path")
        return str(path)

    @field_validator("path")
    @classmethod
    def path_must_start_with_slash(cls, value: str) -> str:
        if not value.startswith("/"):
            raise ValueError('path must start with "/"')
        return _normalize_config_path(value)

    @field_validator("token_issue_path")
    @classmethod
    def token_issue_path_format(cls, value: str) -> str:
        value = value.strip()
        if not value:
            return ""
        if not value.startswith("/"):
            raise ValueError('token_issue_path must start with "/"')
        return _normalize_config_path(value)

    @model_validator(mode="after")
    def token_issue_path_differs_from_ws_path(self) -> Self:
        if not self.token_issue_path:
            return self
        if _normalize_config_path(self.token_issue_path) == _normalize_config_path(self.path):
            raise ValueError("token_issue_path must differ from path (the WebSocket upgrade path)")

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Add the leading slash: path: /ws
2. If the value comes from an env var, update it to include the leading slash and audit other path-like settings in the same file
3. When concatenating paths programmatically, use '/' + endpoint.lstrip('/')

Example fix

# before
path = "ws"
# after
path = "/ws"

ws_path = "/" + raw_path.lstrip("/")  # normalize before config
assert WebSocketConfig(path=ws_path)  # or: assert ws_path.startswith("/")

def is_valid_ws_path(p: str) -> bool:
    return isinstance(p, str) and p.startswith("/")

When it happens

Trigger: Setting path="ws" or path="connect" instead of "/ws" / "/connect" in the channel config. Any value whose first character is not '/' raises.

Common situations: YAML/JSON config copied from a client-side URL where the leading slash was dropped; building the path by concatenation like "" + endpoint; env var WEBSOCKET_PATH=ws without the slash; template interpolation omitting the leading '/'.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• token_issue_path must start with "/"
• unix_socket_path must not contain NUL bytes
• unix_socket_path must be an absolute path
• token_issue_path must differ from path (the WebSocket upgrad
• host is 0.0.0.0 (all interfaces) but neither token nor token

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/a572e5e4e087fee1. Report an issue: GitHub.