HKUDS/Vibe-Trading · error · ValueError

unix_socket_path must be an absolute path

Error message

unix_socket_path must be an absolute path

What it means

Raised when unix_socket_path (after ~ expansion via Path.expanduser) is not absolute, e.g. "run/app.sock" or "./app.sock". Binding a relative unix socket path depends on the process's current working directory, which makes the socket location unpredictable, so an absolute path is required.

Source

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

    # (base64 overhead) + envelope framing stays under 36 MB; the 40 MB ceiling
    # leaves a small margin for sender slop without opening a DoS avenue.
    max_message_bytes: int = Field(default=37_748_736, ge=1024, le=41_943_040)
    ping_interval_s: float = Field(default=20.0, ge=5.0, le=300.0)
    ping_timeout_s: float = Field(default=20.0, ge=5.0, le=300.0)
    ssl_certfile: str = ""
    ssl_keyfile: str = ""

    @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)

View on GitHub (pinned to 80ffdda44c)

Solutions

  1. Use a fully qualified absolute path like "/var/run/app/ws.sock"
  2. If using ~, ensure HOME is set in the service environment (systemd: Environment= or WorkingDirectory plus absolute path preferred)
  3. Create the parent directory and confirm permissions before starting the channel

Example fix

# before
unix_socket_path = "./ws.sock"
# after
unix_socket_path = "/var/run/myapp/ws.sock"
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def ok_socket_path(p: str) -> bool:
    v = p.strip()
    return v == "" or ("\x00" not in v and Path(v).expanduser().is_absolute())

Type guard

def is_absolute_socket_path(p: str) -> bool:
    return Path(p.strip()).expanduser().is_absolute()

Prevention

When it happens

Trigger: Setting unix_socket_path="app.sock", "./tmp/ws.sock", or "~/sockets/ws.sock" where ~ fails to expand (HOME unset). Path(value).expanduser().is_absolute() is False, so the validator raises.

Common situations: Using a relative path that worked in one working directory but breaks under systemd/containers where cwd differs; templating config with a missing leading slash; HOME not set in a hardened service environment so expanduser() is a no-op on a ~/... path.

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

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