What causes "ENVIO_API_TOKEN environment variable must be set" in nautechsystems/nautilus_trader?

Export `ENVIO_API_TOKEN= ` in the shell or service environment before starting the process.

nautechsystems/nautilus_trader · critical

ENVIO_API_TOKEN environment variable must be set

Error message

ENVIO_API_TOKEN environment variable must be set

What it means

`HypersyncClient::new` reads the HyperSync API token with `std::env::var("ENVIO_API_TOKEN").expect("ENVIO_API_TOKEN environment variable must be set")`, panicking when the variable is absent from the process environment. HyperSync requires an Envio API token (a UUID) for authenticated access, and since the constructor cannot return `Result`, a missing token aborts the process. The variable must be exported before the process starts; setting it at runtime within the process is too late.

Source

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

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

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

View on GitHub (pinned to 18893faf8b)

Solutions

Export `ENVIO_API_TOKEN=<your-uuid-token>` in the shell or service environment before starting the process.
Add the variable to your CI secret store and deployment manifests.
In local dev, source a `.env` file (e.g. with dotenvy) or export it in your shell profile.
Fail fast in your own bootstrap code: check `std::env::var("ENVIO_API_TOKEN")` and emit a clear message before constructing the client.

Example fix

// before
let client = HypersyncClient::new(chain, tx, token); // panics if ENVIO_API_TOKEN unset
// after
if std::env::var("ENVIO_API_TOKEN").is_err() {
    anyhow::bail!("ENVIO_API_TOKEN must be set to use HyperSync");
}
let client = HypersyncClient::new(chain, tx, token);

Defensive patterns

Strategy: validation

Validate before calling

fn require_envio_token() -> Result<String, String> {
    std::env::var("ENVIO_API_TOKEN")
        .ok()
        .filter(|t| !t.trim().is_empty())
        .map(|t| t.trim().to_string())
        .ok_or_else(|| "ENVIO_API_TOKEN must be exported before starting".to_string())
}

Try / catch

// Check at process startup, not inside the client constructor
let _token = require_envio_token().map_err(|e| { eprintln!("{e}"); std::process::exit(1) });

Prevention

Document ENVIO_API_TOKEN in the project README/setup script and check it in a startup assertion.
Add the secret to CI and container env configuration before running integration tests.
Use dotenvy locally and commit a `.env.example` listing required variables.

When it happens

Trigger: Constructing the HyperSync client in a process launched without `ENVIO_API_TOKEN` exported in its environment — e.g. running tests, a binary, or a container where the variable was never set.

Common situations: Running `cargo test` locally without a `.env`/shell export; CI pipelines lacking the secret; Docker/Kubernetes deployments missing the env var; a typo like `ENVIO_API_TOKEN` vs `ENVIO_TOKEN`.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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