zeroclaw-labs/zeroclaw · error

unknown eval mode '{other}' (expected 'replay' or 'live')

Error message

unknown eval mode '{other}' (expected 'replay' or 'live')

What it means

Thrown by `Mode::from_str` in zeroclaw-eval when the mode string, after trim + ASCII lowercase, is neither `replay` nor `live`. The eval harness uses this to parse its `--mode` argument, so any unsupported or misspelled value reaches this error. Matching is deliberately case- and whitespace-insensitive (`Replay` and ` LIVE ` are accepted), so the failure always means the value itself is wrong.

Source

Thrown at crates/zeroclaw-eval/src/lib.rs:36

/// How an evaluation suite is executed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Mode {
    /// Deterministic replay against scripted LLM responses — no network, no cost.
    Replay,
    /// Live execution against a real provider. Added in a later phase; the Phase 0
    /// runner returns a clear error so the variant can already be parsed from the CLI.
    Live,
}

impl FromStr for Mode {
    type Err = anyhow::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.trim().to_ascii_lowercase().as_str() {
            "replay" => Ok(Mode::Replay),
            "live" => Ok(Mode::Live),
            other => anyhow::bail!("unknown eval mode '{other}' (expected 'replay' or 'live')"),
        }
    }
}

impl std::fmt::Display for Mode {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            Mode::Replay => "replay",
            Mode::Live => "live",
        })
    }
}

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Use `--mode replay` — the only mode Phase 0 actually runs (`live` parses but `run_suite` rejects it)
2. Check the argument for typos, trailing characters, or shell quoting issues
3. If calling from Rust code, construct `Mode::Replay` directly instead of parsing a string

Example fix

# before
zeroclaw-eval --mode repaly ./traces
# after
zeroclaw-eval --mode replay ./traces

fn is_known_eval_mode(s: &str) -> bool {
    matches!(s.trim().to_ascii_lowercase().as_str(), "replay" | "live")
}

// before parsing:
if !is_known_eval_mode(&cli.mode) {
    eprintln!("--mode must be 'replay' or 'live'");
    std::process::exit(2);
}

fn as_eval_mode(s: &str) -> Option<zeroclaw_eval::Mode> {
    match s.trim().to_ascii_lowercase().as_str() {
        "replay" => Some(zeroclaw_eval::Mode::Replay),
        "live" => Some(zeroclaw_eval::Mode::Live),
        _ => None,
    }
}

let mode = match zeroclaw_eval::Mode::from_str(&cli.mode) {
    Ok(m) => m,
    Err(e) => {
        eprintln!("invalid --mode: {e}");
        print_usage();
        return;
    }
};

When it happens

Trigger: Calling the eval CLI (or `Mode::from_str` directly) with `--mode repaly`, `--mode offline`, `--mode record`, or an empty string. Any value that is not exactly `replay` or `live` after trimming and lowercasing.

Common situations: Typos on the command line; assuming a mode exists that was never implemented (only `replay` and `live` parse, and `live` is rejected later by `run_suite` in Phase 0); piping an unset/empty environment variable into the mode argument.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• TraceLlmProvider({}): turn {turn_index} scripted {leftover}
• TraceLlmProvider({}): turn {current} requested more LLM resp
• live mode is not implemented yet (Phase 0 supports --mode re
• no *.json trace fixtures found in {}
• Unknown init system: '{}'. Supported: auto, systemd, openrc

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/d5d32b3bb579a2f1. Report an issue: GitHub.