nautechsystems/nautilus_trader · error

{description} endpoint fragments are unsupported

Error message

{description} endpoint fragments are unsupported

What it means

Thrown by `validate_execution_endpoint` when the endpoint URL contains a fragment (`#...`). Fragments are never sent to servers and have no meaning for JSON-RPC endpoints, so the validator rejects them to keep endpoint canonicalization exact.

Source

Thrown at crates/adapters/blockchain/src/rpc/http.rs:926

    }
}

#[cfg(feature = "hypersync")]
pub(crate) fn validate_execution_endpoint(
    endpoint: &str,
    description: &str,
) -> anyhow::Result<Url> {
    let url =
        Url::parse(endpoint).map_err(|_| anyhow::anyhow!("Invalid {description} endpoint"))?;
    anyhow::ensure!(
        matches!(url.scheme(), "http" | "https"),
        "{description} endpoint must use HTTPS or canonical loopback HTTP"
    );
    anyhow::ensure!(
        url.host().is_some(),
        "{description} endpoint host is required"
    );
    anyhow::ensure!(
        url.fragment().is_none(),
        "{description} endpoint fragments are unsupported"
    );
    anyhow::ensure!(
        url.scheme() == "https" || is_canonical_loopback_endpoint(endpoint),
        "{description} endpoint must use HTTPS unless its host is a canonical loopback IP literal"
    );
    Ok(url)
}

fn is_canonical_loopback_endpoint(endpoint: &str) -> bool {
    let Some((scheme, rest)) = endpoint.split_once("://") else {
        return false;
    };

    if !scheme.eq_ignore_ascii_case("http") && !scheme.eq_ignore_ascii_case("https") {
        return false;
    }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Strip everything from `#` onward in the endpoint string.
2. Use the provider's documented raw RPC URL, not a dashboard/UI URL.
3. Sanitize config inputs by trimming fragments before constructing the client.

Example fix

// before
let endpoint = "https://node.example.com#settings"; // fragment rejected
// after
let endpoint = "https://node.example.com";

let cleaned = endpoint.split('#').next().unwrap_or(endpoint);
let url = url::Url::parse(cleaned)?;
anyhow::ensure!(url.fragment().is_none(), "strip the '#...' fragment from the endpoint");

fn fragment_free(s: &str) -> bool {
    url::Url::parse(s).map(|u| u.fragment().is_none()).unwrap_or(false)
}

let client = HttpRpcClient::new(endpoint).map_err(|e| {
    if e.to_string().contains("fragments are unsupported") {
        anyhow::anyhow!("endpoint '{endpoint}' contains a '#fragment'; copy the raw RPC URL from the provider")
    } else { e.into() }
})?;

When it happens

Trigger: Endpoint strings copied from browser address bars or docs that carry a `#fragment` suffix (e.g. `https://node.example.com#readme`, `https://host/#/dashboard`) passed to `new` or `normalize_endpoint`.

Common situations: Copy-pasting a provider dashboard URL (with SPA hash routes) instead of the raw RPC endpoint URL; appending `#anchor` notes to config values; secret-in-fragment mistakes.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Invalid {description} endpoint
• {description} endpoint must use HTTPS or canonical loopback
• {description} endpoint host is required
• request_rate_per_second must be greater than zero
• order_request_rate_per_second must be greater than zero

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