nautechsystems/nautilus_trader · critical

Failed to create HyperSync client - check ENVIO_API_TOKEN is

Error message

Failed to create HyperSync client - check ENVIO_API_TOKEN is a valid UUID

What it means

After loading the config, `HypersyncClient::new` calls `hypersync_client::Client::new(config).expect("Failed to create HyperSync client - check ENVIO_API_TOKEN is a valid UUID")`. The underlying client constructor returns a `Result` and fails when the provided `ENVIO_API_TOKEN` is not the valid UUID the Envio API expects (or the client cannot be initialized at all). Because the wrapper cannot return `Result`, an invalid token aborts the process at construction time. Note the token is read successfully here — it exists, but its value is wrong.

Source

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

    /// 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,
        }
    }

    #[must_use]
    pub fn get_pool_address(&self, instrument_id: InstrumentId) -> Option<&Address> {
        self.pool_addresses.get(&instrument_id)
    }

View on GitHub (pinned to 18893faf8b)

Solutions

Set `ENVIO_API_TOKEN` to the exact UUID-formatted token from your Envio account, without quotes or stray whitespace.
Regenerate the token in the Envio dashboard if it may have been revoked, and update the environment.
Strip whitespace/newlines from the value at the source (e.g. `.trim()` when reading dotenv files).
Handle the underlying `Client::new` error explicitly in your own setup to get the detailed message instead of the panic.

Example fix

// before
ENVIO_API_TOKEN=my-token-here cargo run   # panics: not a valid UUID
// after
ENVIO_API_TOKEN=550e8400-e29b-41d4-a716-446655440000 cargo run

Defensive patterns

Strategy: validation

Validate before calling

fn validate_envio_token_format() -> Result<(), String> {
    let token = std::env::var("ENVIO_API_TOKEN").map_err(|_| "ENVIO_API_TOKEN not set".to_string())?;
    let t = token.trim();
    let is_uuid = t.len() == 36
        && t.chars().enumerate().all(|(i, c)| {
            matches!(i, 8 | 13 | 18 | 23) == (c == '-')
                && (c == '-' || c.is_ascii_hexdigit())
        });
    if is_uuid { Ok(()) } else { Err("ENVIO_API_TOKEN must be a UUID".to_string()) }
}

Try / catch

// Reject malformed tokens before client construction
validate_envio_token_format().map_err(|e| anyhow::anyhow!(e))?;

Prevention

Copy tokens without surrounding quotes; trim trailing newlines from dotenv values.
Regenerate tokens after rotation and update all environments at once.
Validate UUID format in a smoke test that runs before integration suites.

When it happens

Trigger: Setting `ENVIO_API_TOKEN` to a placeholder, truncated value, non-UUID string, empty string, or a revoked/expired token, then constructing the HyperSync client.

Common situations: A dummy token copied from documentation; quotes/whitespace or a newline accidentally included in the env value; a token regenerated server-side so the old one is revoked; pasting a non-Envio API key by mistake.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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