nautechsystems/nautilus_trader · critical

Lighter execution client requires credentials; set private_k

Error message

Lighter execution client requires credentials; set private_key, account_index, and api_key_index in the config or use the deployment-specific credential environment variables

What it means

The Lighter execution client validates at startup (before any WS/REST work) that credentials are present: private_key, account_index, and api_key_index. Without them the engine would accept the connection but deny every order per-submission, so the client fails fast with this message instead of letting reconciliation and strategies start in a broken state.

Source

Thrown at crates/adapters/lighter/src/execution.rs:4044

        self.begin_session_shutdown();
        Ok(())
    }

    fn dispose(&mut self) -> anyhow::Result<()> {
        log::debug!("Disposing Lighter execution client {}", self.core.client_id);
        self.stop()
    }

    async fn connect(&mut self) -> anyhow::Result<()> {
        if self.core.is_connected() && self.pending_tasks.is_open() {
            return Ok(());
        }

        // Without credentials the engine would accept the connection and
        // then deny every order per-submission. Fail before any WS/REST
        // work so reconciliation and strategies never start.
        if !self.has_credentials() {
            anyhow::bail!(
                "Lighter execution client requires credentials; \
                 set private_key, account_index, and api_key_index in the config \
                 or use the deployment-specific credential environment variables"
            );
        }

        log::info!(
            "Connecting Lighter execution client {}",
            self.core.client_id
        );

        // Synchronous stop/reset can only initiate teardown. Complete it before
        // publishing a replacement socket or sharing its connection epoch.
        if !self.session_tasks_finished() || !self.pending_tasks.is_open() {
            self.begin_session_shutdown();
            self.finish_session_shutdown().await?;
        }

View on GitHub (pinned to 18893faf8b)

Solutions

Set private_key, account_index, and api_key_index in the Lighter adapter config
Or set the deployment-specific credential environment variables the adapter reads
Verify the secret injection (env/file mount) actually ran in the deployment environment
Re-check config key spelling and that the correct config file/profile is loaded

Example fix

// before: incomplete config
{
  "execution": { "adapter": "lighter" }
}
// after
{
  "execution": {
    "adapter": "lighter",
    "private_key": "0x...",
    "account_index": 1,
    "api_key_index": 0
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Rust: validate credentials before constructing the client
fn validate_lighter_config(cfg: &LighterExecConfig) -> Result<(), String> {
    if cfg.private_key.is_empty() || cfg.account_index.is_none() || cfg.api_key_index.is_none() {
        return Err("lighter execution requires private_key, account_index, api_key_index".into());
    }
    Ok(())
}

Type guard

fn has_credentials(cfg: &LighterExecConfig) -> bool {
    cfg.private_key.as_deref().map_or(false, |k| !k.is_empty())
        && cfg.account_index.is_some()
        && cfg.api_key_index.is_some()
}

Try / catch

let client = match LighterExecutionClient::new(cfg) {
    Err(e) if e.to_string().contains("requires credentials") => {
        eprintln!("set LIGHTER_PRIVATE_KEY / LIGHTER_ACCOUNT_INDEX / LIGHTER_API_KEY_INDEX");
        return Err(e);
    }
    r => r?,
};

Prevention

Validate config completeness at deployment start, before engine startup
Inject credentials via env vars in containers and assert they are non-empty
Add a startup smoke test that constructs the client with the deployment config

When it happens

Trigger: Constructing/starting the Lighter execution client with a config missing any of private_key, account_index, or api_key_index, and with no deployment-specific credential environment variables set (has_credentials() returns false).

Common situations: Empty or partial config files, env vars not exported in the deployment environment (containers, CI), typos in config keys, or secrets managed by a secret store that failed to inject.

Related errors

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