nautechsystems/nautilus_trader · error

environment variable '{key}' is not valid Unicode

Error message

environment variable '{key}' is not valid Unicode

What it means

`get_env_var` errors when the environment variable exists but contains bytes that are not valid Unicode (std::env::VarError::NotUnicode). Rust environment values are OsStrings and may hold arbitrary bytes; this API only returns String, so a non-UTF-8 value is unusable and rejected.

Source

Thrown at crates/core/src/env.rs:33

//! Cross-platform environment variable utilities.
//!
//! This module provides functions for safely accessing environment variables
//! with proper error handling.

/// Returns the value of the environment variable for the given `key`.
///
/// # Errors
///
/// Returns an error if the environment variable is not set or is not valid Unicode.
pub fn get_env_var(key: &str) -> anyhow::Result<String> {
    match std::env::var(key) {
        Ok(var) => Ok(var),
        Err(std::env::VarError::NotPresent) => {
            anyhow::bail!("environment variable '{key}' must be set")
        }
        Err(std::env::VarError::NotUnicode(_)) => {
            anyhow::bail!("environment variable '{key}' is not valid Unicode")
        }
    }
}

/// Returns the provided `value` if `Some`, otherwise falls back to reading
/// the environment variable for the given `key`.
///
/// Only attempts to read the environment variable when `value` is `None`,
/// avoiding unnecessary environment variable lookups and errors.
///
/// # Errors
///
/// Returns an error if `value` is `None` and the environment variable is not set.
pub fn get_or_env_var(value: Option<String>, key: &str) -> anyhow::Result<String> {
    match value {
        Some(v) => Ok(v),
        None => get_env_var(key),
    }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Re-set the variable with a valid UTF-8 value: export KEY='clean value'
2. Find what is setting the variable non-Unicode (scripts, supervisor configs, OS locale) and fix the encoding
3. If raw bytes are expected, read via std::env::var_os yourself and decode explicitly instead of get_env_var

Example fix

// before
let val = get_env_var("MY_KEY")?; // fails if MY_KEY has non-UTF8 bytes
// after
let val = match std::env::var_os("MY_KEY") {
    Some(v) => String::from_utf8_lossy(v.as_encoded_bytes()).into_owned(),
    None => anyhow::bail!("environment variable 'MY_KEY' must be set"),
};

if let Some(raw) = std::env::var_os("MY_KEY") {
    if raw.to_str().is_none() {
        eprintln!("MY_KEY contains non-UTF-8 bytes");
    }
}

fn is_utf8_env(key: &str) -> bool {
    std::env::var_os(key)
        .map(|v| v.to_str().is_some())
        .unwrap_or(false)
}

match get_env_var("MY_KEY") {
    Ok(v) => use(v),
    Err(e) if e.to_string().contains("not valid Unicode") => {
        // re-set the variable or read via var_os and lossy-decode
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling `get_env_var(key)` when the variable was set with non-UTF-8 bytes (e.g. via a low-level setenv, binary data, or a corrupted shell/launcher environment).

Common situations: Values pasted from Windows or legacy encodings (Latin-1, Shift-JIS) into a Unix environment; a script exporting binary/blob data; container images or process supervisors setting garbled values.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• missing broker client order ID signal
• unknown broker client order ID signal byte '{}'
• environment variable '{key}' must be set
• LiveNode cannot be used with Backtest environment
• Missing environment variable: {key_env}

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