nautechsystems/nautilus_trader · error · anyhow::Error

unrecognized side

Error message

unrecognized side '{side}'

What it means

When loading Binance order-book delta CSV data, map_row normalizes the side column: 'b' maps to BUY and 'a' to SELL. Any other value in the side column cannot be translated to the internal enum, so loading the row fails with this message naming the offending raw value.

Solutions

  1. Inspect the offending CSV row's side column and fix it to 'b' or 'a'
  2. Validate/preprocess the CSV: drop or repair rows whose side is not b/a before loading
  3. Confirm the file is an official Binance order-book depth dump (side column is b/a, update_type snap/update) and not another dataset format
  4. If your Binance export uses different tokens, normalize them in a preprocessing pass (e.g. map 'buy'->'b') before handing the file to the loader

Example fix

// before
df = pd.read_csv(path)  # side column contains 'buy'/'sell'
// after
df = pd.read_csv(path)
df["side"] = df["side"].str.lower().map({"b": "b", "a": "a", "buy": "b", "sell": "a"})
assert df["side"].isin(["b", "a"]).all(), df.loc[~df["side"].isin(["b", "a"]), "side"].unique()
Defensive patterns

Strategy: validation

Validate before calling

import csv
with open(path) as f:
    bad = [row["side"] for row in csv.DictReader(f) if row["side"].strip().lower() not in ("b", "a")]
assert not bad, f"rows with invalid side: {bad[:5]}"

Type guard

def is_valid_side(value: str) -> bool:
    return value.strip().lower() in ("b", "a")

Try / catch

try:
    rows = load_rows(path)
except Exception as e:
    if "unrecognized side" in str(e):
        print("CSV side column invalid — clean/repair the file and retry")
    else:
        raise

Prevention

When it happens

Trigger: Calling the CSV data loader (load_rows) on a Binance order-book delta CSV whose side column contains a value other than 'b' or 'a' (case-insensitive) — e.g. an empty field, a corrupted row, or a CSV from a different export format.

Common situations: Hand-edited or truncated download files; using a market/dataset whose CSV schema differs from the expected Binance depth-dump format (e.g. full 'buy'/'sell' words or numeric sides); mixing columns after custom preprocessing.

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


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

Appendix: source

Thrown at crates/adapters/binance/src/python/data.rs:93

    let mut reader = csv::Reader::from_path(file_path).with_context(|| {
        format!(
            "failed to open Binance order book CSV {}",
            file_path.display(),
        )
    })?;

    reader
        .deserialize::<BinanceOrderBookDeltaCsvRow>()
        .take(nrows.unwrap_or(usize::MAX))
        .map(|row| map_row(&row?))
        .collect()
}

fn map_row(row: &BinanceOrderBookDeltaCsvRow) -> anyhow::Result<BinanceOrderBookDeltaRow> {
    let side = match row.side.to_ascii_lowercase().as_str() {
        "b" => "BUY",
        "a" => "SELL",
        side => anyhow::bail!("unrecognized side '{side}'"),
    };
    let is_snapshot = row.update_type == "snap";
    let action = if is_snapshot {
        "ADD"
    } else if row.qty == 0.0 {
        "DELETE"
    } else {
        "UPDATE"
    };

    Ok(BinanceOrderBookDeltaRow {
        timestamp: row.timestamp,
        instrument_id: format!("{}.BINANCE", row.symbol),
        action,
        side,
        price: row.price,
        size: row.qty,
        order_id: 0,

View on GitHub (pinned to 18893faf8b)