nautechsystems/nautilus_trader · error

Lighter API key index must be in 0..=254

Error message

Lighter API key index must be in 0..=254

What it means

The Lighter credential loader validates that the API key index is a u8 in the range 0..=254 (255 is reserved). `ensure_api_key_index` rejects any value above 254 with this error. The index is read from an environment variable or passed directly by `new`, `resolve_api_key_index`, or `parse_api_key_index`.

Source

Thrown at crates/adapters/lighter/src/common/credential.rs:316

            .map(|s| {
                s.trim()
                    .parse::<u64>()
                    .with_context(|| format!("{env_var} must be an unsigned integer"))
            })
            .transpose(),
    }
}

fn parse_api_key_index(value: &str, env_var: &str) -> anyhow::Result<u8> {
    let index = value
        .trim()
        .parse::<u8>()
        .with_context(|| format!("{env_var} must be an API key index in 0..=254"))?;
    ensure_api_key_index(index)
}

fn ensure_api_key_index(value: u8) -> anyhow::Result<u8> {
    anyhow::ensure!(value <= 254, "Lighter API key index must be in 0..=254");
    Ok(value)
}

fn decode_private_key_hex(value: &str) -> anyhow::Result<Vec<u8>> {
    let value = value.trim();
    let hex = value
        .strip_prefix("0x")
        .or_else(|| value.strip_prefix("0X"))
        .unwrap_or(value);
    let bytes = hex::decode(hex).context("Lighter API secret must be valid hex")?;
    anyhow::ensure!(
        bytes.len() == SCALAR_BYTES,
        "Lighter API secret must be a 40-byte hex private key"
    );
    Ok(bytes)
}

#[cfg(test)]

View on GitHub (pinned to 18893faf8b)

Solutions

1. Set the API key index env var to an integer between 0 and 254 inclusive.
2. Confirm with your Lighter account which API key indices are actually provisioned and use one of those.
3. Re-read the documentation: 255 is reserved and never valid.

Example fix

// before
LIGHTER_API_KEY_INDEX=255
// after
LIGHTER_API_KEY_INDEX=2

let idx: u8 = std::env::var("LIGHTER_API_KEY_INDEX")?.parse()?;
assert!(idx <= 254, "Lighter API key index must be in 0..=254");

fn is_valid_api_key_index(v: u8) -> bool { v <= 254 }

let creds = LighterCredentials::from_env().map_err(|e| {
    eprintln!("Lighter credential config error: {e:#}");
    e
})?;

When it happens

Trigger: Setting the Lighter API key index env var to a value like `255` or any integer > 254, or calling `new`/`ensure_api_key_index` with an out-of-range index.

Common situations: Typos or misconfigured credentials in the environment; copying an index from a different system that allows 255; misunderstanding that 255 is reserved by the Lighter API.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• `max_quote_age_blocks` must be in 1..=4095
• Lighter API secret must be a 40-byte hex private key
• Missing Betfair credentials in config and environment
• Invalid Betfair credentials: username provided but password
• Invalid Betfair credentials: password or app key provided bu

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