nautechsystems/nautilus_trader · critical

Invalid HyperSync URL

Error message

Invalid HyperSync URL

What it means

`HypersyncClient::new` builds a `hypersync_client::ClientConfig` from the chain's `hypersync_url` and calls `.expect("Invalid HyperSync URL")` on `validate_execution_endpoint`, panicking when the URL fails validation (unparseable/empty/not a valid endpoint). This code runs in a constructor that cannot return `Result`, so any misconfigured chain URL aborts the process at client construction time. It is a configuration-time failure, not a network failure.

Source

Thrown at crates/adapters/blockchain/src/hypersync/client.rs:109

impl HyperSyncClient {
    /// Creates a new [`HyperSyncClient`] instance for the given chain and message sender.
    ///
    /// # Panics
    ///
    /// Panics if:
    /// - The chain's `hypersync_url` is invalid.
    /// - The `ENVIO_API_TOKEN` environment variable is not set or invalid.
    /// - The underlying client cannot be initialized.
    #[must_use]
    pub fn new(
        chain: SharedChain,
        tx: Option<tokio::sync::mpsc::UnboundedSender<BlockchainMessage>>,
        cancellation_token: tokio_util::sync::CancellationToken,
    ) -> Self {
        let mut config = hypersync_client::ClientConfig::default();
        let hypersync_url = validate_execution_endpoint(chain.hypersync_url.as_str(), "HyperSync")
            .expect("Invalid HyperSync URL");
        config.url = hypersync_url.to_string();
        config.api_token = std::env::var("ENVIO_API_TOKEN")
            .expect("ENVIO_API_TOKEN environment variable must be set");

        let client = hypersync_client::Client::new(config)
            .expect("Failed to create HyperSync client - check ENVIO_API_TOKEN is a valid UUID");

        Self {
            chain,
            client: Arc::new(client),
            blocks_task: TaskSlot::new(),
            blocks_cancellation_token: None,
            dex_event_tasks: AHashMap::new(),
            tx,
            pool_addresses: AHashMap::new(),
            cancellation_token,
        }
    }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Fix the `hypersync_url` on the chain config to a valid, reachable endpoint URL (e.g. https://eth.hypersync.xyz).
2. Run the URL through `validate_execution_endpoint` (or a URL parse) in your own setup code first to get a descriptive error before client construction.
3. Check where the chain config is loaded — an empty or mis-interpolated value is the usual culprit.
4. If self-hosting HyperSync, confirm the base URL scheme and host are correct.

Example fix

// before
let client = HypersyncClient::new(chain, tx, token); // panics if chain.hypersync_url is invalid
// after
let url = validate_execution_endpoint(chain.hypersync_url.as_str(), "HyperSync")
    .map_err(|e| anyhow::anyhow!("bad hypersync url for {}: {e}", chain.name))?;
let client = HypersyncClient::new(chain, tx, token);

fn check_hypersync_url(chain: &SharedChain) -> Result<(), String> {
    let url = chain.hypersync_url.trim();
    if url.is_empty() || !url.starts_with("https://") {
        return Err(format!("chain {} has invalid hypersync_url: {:?}", chain.name, url));
    }
    url::Url::parse(url).map(|_| ()).map_err(|e| e.to_string())
}

// Fail fast in bootstrap before constructing the client
check_hypersync_url(&chain).map_err(|e| anyhow::anyhow!(e))?;

When it happens

Trigger: Constructing the HyperSync client for a `SharedChain` whose `hypersync_url` is empty, malformed (e.g. missing scheme, typo, whitespace), or otherwise rejected by `validate_execution_endpoint`.

Common situations: A typo'd or deprecated HyperSync endpoint in chain configuration; a custom/self-hosted HyperSync instance whose URL string is wrong; a config file or env value interpolated incorrectly leaving the URL blank.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• ENVIO_API_TOKEN environment variable must be set
• Failed to create HyperSync client - check ENVIO_API_TOKEN is
• Unsupported blockchain {blockchain} for RPC connection
• Kraken Spot does not support the demo environment
• Redis config error: username supplied without password. Eith

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