nautechsystems/nautilus_trader · error · anyhow::Error

Socket endpoint must contain only ASCII letters, digits, '.'

Error message

Socket endpoint must contain only ASCII letters, digits, '.', '-', or '_'

What it means

socket_endpoint restricts endpoint characters to ASCII letters, digits, '.', '-', and '_'. Any other byte (spaces, slashes, colons, '@', unicode, etc.) causes this error. The restriction keeps endpoints safe as identifiers in socket command routing.

Source

Thrown at crates/common/src/messages/system/socket.rs:39

#[cfg(any(feature = "live", test))]
const ENDPOINT_MAX_LEN: usize = 128;

#[cfg(any(feature = "live", test))]
pub(crate) fn socket_endpoint(endpoint: &str) -> anyhow::Result<Ustr> {
    if endpoint.is_empty() {
        anyhow::bail!("Socket endpoint cannot be empty");
    }

    if endpoint.len() > ENDPOINT_MAX_LEN {
        anyhow::bail!("Socket endpoint cannot exceed {ENDPOINT_MAX_LEN} bytes");
    }

    if !endpoint
        .bytes()
        .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-' | b'_'))
    {
        anyhow::bail!("Socket endpoint must contain only ASCII letters, digits, '.', '-', or '_'");
    }

    Ok(Ustr::from(endpoint))
}

/// Command requesting reconnect of one socket endpoint owned by one client.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(
    feature = "python",
    pyo3::pyclass(module = "nautilus_trader.common", from_py_object)
)]
#[cfg_attr(
    feature = "python",
    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.common")
)]
pub struct ReconnectSocket {
    pub trader_id: TraderId,

View on GitHub (pinned to 18893faf8b)

Solutions

1. Strip the URL scheme and port, keeping only the endpoint name portion composed of allowed characters.
2. Trim whitespace and ensure environment variable substitution happened before validation.
3. Sanitize the endpoint: replace disallowed characters ('/', ':', spaces) with '-' or '_' when deriving names from addresses.
4. Validate the character set at config-load time with your own pre-check to produce a friendlier error.

Example fix

// before
let ep = socket_endpoint("tcp://my-host:7323")?;
// after
let ep = socket_endpoint("my-host")?; // ASCII letters, digits, '.', '-', '_' only

fn endpoint_charset_ok(s: &str) -> bool {
    s.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'-' | b'_'))
}

fn valid_endpoint(s: &str) -> bool { !s.is_empty() && s.len() <= 128 && s.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'-' | b'_')) }

let ep = socket_endpoint(endpoint)
    .map_err(|e| anyhow::anyhow!("endpoint '{endpoint}' has invalid characters: {e}"))?;

When it happens

Trigger: Calling socket_endpoint with strings containing ':' (URL schemes/ports), '/' (paths), whitespace, or non-ASCII characters — e.g. passing `tcp://host:7323` or `my endpoint`.

Common situations: Config values copied from connection strings or URLs, endpoints containing environment placeholders like `${HOST}` that were not substituted, or trailing whitespace/newline from env variables.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Socket endpoint cannot be empty
• Socket endpoint cannot exceed {ENDPOINT_MAX_LEN} bytes
• {e}
• {FAILED}: {e}
• {FAILED}: {e}

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/3839e63b4f8f164c. Report an issue: GitHub.