HKUDS/Vibe-Trading · error · ValueError

token_issue_path must start with "/"

Error message

token_issue_path must start with "/"

What it means

Raised when token_issue_path is non-empty but does not start with '/'. token_issue_path defines the HTTP endpoint that issues auth tokens for the WebSocket channel; like the main path, it must be a root-relative URL path, which the validator enforces before normalizing it.

Source

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

        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)")
        return self

    @model_validator(mode="after")
    def wildcard_host_requires_auth(self) -> Self:
        if self.host not in ("0.0.0.0", "::"):
            return self
        if self.token.strip() or self.token_issue_secret.strip():
            return self
        raise ValueError(
            "host is 0.0.0.0 (all interfaces) but neither token nor "

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Set token_issue_path: /token (leading slash required)
2. Leave it empty/omit it if you don't need token issuance over HTTP
3. Cross-check the related path field uses the same leading-slash convention

Example fix

# before
token_issue_path = "issue-token"
# after
token_issue_path = "/issue-token"

if token_issue_path:
    token_issue_path = "/" + token_issue_path.lstrip("/")
# empty string is fine (issuance disabled)

def is_valid_issue_path(p: str) -> bool:
    return p == "" or p.startswith("/")

When it happens

Trigger: Setting token_issue_path="issue" or "auth/token" in config (empty string is allowed and skips validation). Any non-empty value not beginning with '/' raises.

Common situations: Configuring token issuance for the first time and reusing a route name without the slash; env var token_issue_path=token missing '/'; copying the value from documentation that showed it without a leading slash.

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

• 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/c5bd731e8dfe3c36. Report an issue: GitHub.