nautechsystems/nautilus_trader · error

{context} fields do not match the version 1 schema

Error message

{context} fields do not match the version 1 schema

What it means

validate_fields compares the exact key set of a JSON object against the version 1 canonical schema's expected keys (order-insensitive, exact set equality). It throws when an object has a missing field, an extra/unknown field, or a typo'd key. It is shared by validate_document, validate_run, validate_statistics, validate_components, and validate_diagnostics, so the {context} prefix identifies which section mismatched.

Source

Thrown at crates/backtest/src/result.rs:364

    let summary = object
        .get("summary")
        .and_then(Value::as_object)
        .ok_or_else(|| anyhow::anyhow!("canonical result summary must be an object"))?;
    anyhow::ensure!(
        summary.values().all(Value::is_string),
        "canonical result summary values must be strings"
    );
    Ok(())
}

fn validate_fields(
    object: &Map<String, Value>,
    expected: &[&str],
    context: &str,
) -> anyhow::Result<()> {
    let actual = object.keys().map(String::as_str).collect::<BTreeSet<_>>();
    let expected = expected.iter().copied().collect::<BTreeSet<_>>();
    anyhow::ensure!(
        actual == expected,
        "{context} fields do not match the version 1 schema"
    );
    Ok(())
}

fn validate_components(value: &Value) -> anyhow::Result<()> {
    let object = value
        .as_object()
        .ok_or_else(|| anyhow::anyhow!("canonical result components must be an object"))?;
    validate_fields(
        object,
        &[
            "actor_ids",
            "exec_algorithm_ids",
            "strategy_ids",
            "trader_state",
        ],

View on GitHub (pinned to 18893faf8b)

Solutions

1. Diff the section's keys against the schema field list in the {context} message and add/remove fields to match exactly
2. Remove extra custom fields or rename misspelled keys to the exact schema names
3. Regenerate the document via the library instead of editing by hand
4. If the document is genuinely from another schema version, migrate it before parsing

Example fix

// before
"run": {"iterations": "1", "outcome": "completed"} // missing fields
// after
"run": {"backtest_end_ns": null, "backtest_start_ns": null, "iterations": "1", "outcome": "completed", "run_config_id": null, "total_events": "0", "total_orders": "0", "total_positions": "0", "trader_id": "TRADER-001"}

fn keys_match(v: &serde_json::Value, expected: &[&str]) -> bool {
    v.as_object().map_or(false, |o| {
        let mut a: Vec<_> = o.keys().collect();
        a.sort();
        let mut e: Vec<_> = expected.iter().collect();
        e.sort();
        a == e
    })
}

match CanonicalResult::from_slice(&bytes) {
    Ok(result) => /* use result */,
    Err(e) if e.to_string().contains("do not match the version 1 schema") => {
        // the message's {context} names the offending section; diff its keys and fix
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Parsing (from_slice) or constructing a document where any validated section (canonical result root, run, statistics, components, diagnostics entries) contains keys that differ from the schema — e.g. omitting 'trader_id' from 'run' or adding a custom 'notes' field.

Common situations: Hand-written or tool-generated result JSON with an added/renamed field; forward- or backward-compatible documents from a different schema version; typos like 'stategy_ids'.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• canonical result summary values must be strings
• canonical result components must be an object
• canonical diagnostic must be an object
• unsupported canonical diagnostic code
• canonical result run must be an object

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