nautechsystems/nautilus_trader · error

unsupported canonical diagnostic code

Error message

unsupported canonical diagnostic code

What it means

The only diagnostic code accepted in a canonical result document is "funding-settlement-failed". validate_diagnostics throws this when a diagnostic object's 'code' is a different string or is not a string at all, refusing unknown or future diagnostic codes.

Source

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

        );
    }
    anyhow::ensure!(
        object.get("trader_state").is_some_and(Value::is_string),
        "canonical trader state must be a string"
    );
    Ok(())
}

fn validate_diagnostics(value: &Value) -> anyhow::Result<()> {
    let diagnostics = value
        .as_array()
        .ok_or_else(|| anyhow::anyhow!("canonical diagnostics must be an array"))?;
    for diagnostic in diagnostics {
        let object = diagnostic
            .as_object()
            .ok_or_else(|| anyhow::anyhow!("canonical diagnostic must be an object"))?;
        validate_fields(object, &["code"], "canonical diagnostic")?;
        anyhow::ensure!(
            object.get("code").and_then(Value::as_str) == Some("funding-settlement-failed"),
            "unsupported canonical diagnostic code"
        );
    }
    Ok(())
}

fn validate_run(value: &Value) -> anyhow::Result<()> {
    let object = value
        .as_object()
        .ok_or_else(|| anyhow::anyhow!("canonical result run must be an object"))?;
    validate_fields(
        object,
        &[
            "backtest_end_ns",
            "backtest_start_ns",
            "iterations",
            "outcome",

View on GitHub (pinned to 18893faf8b)

Solutions

1. Change the diagnostic's code to "funding-settlement-failed", the only supported value
2. Remove unsupported diagnostic entries from the document
3. If the document came from a newer version, parse it with a matching library version
4. Ensure the code field is a string, not a number or null

Example fix

// before
{"code": "margin-call"}
// after
{"code": "funding-settlement-failed"}

fn diagnostic_codes_supported(d: &[serde_json::Value]) -> bool {
    d.iter().all(|x| x.get("code").and_then(|c| c.as_str()) == Some("funding-settlement-failed"))
}

fn is_supported_code(v: &serde_json::Value) -> bool {
    v.get("code").and_then(|c| c.as_str()) == Some("funding-settlement-failed")
}

match CanonicalResult::from_slice(&bytes) {
    Ok(result) => /* use result */,
    Err(e) if e.to_string().contains("unsupported canonical diagnostic code") => /* drop or remap unsupported diagnostics, or upgrade the library */,
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: from_slice with a diagnostic like {"code": "order-rejected"} or {"code": 42}; a producer emitting a new diagnostic code the current schema version does not recognize.

Common situations: Documents written by a newer library version introducing new diagnostic codes parsed by an older version; custom tooling inventing its own codes; a null code after failed serialization.

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

• canonical result summary values must be strings
• {context} fields do not match the version 1 schema
• canonical result components must be an object
• canonical diagnostic must be an object
• canonical result run must be an object

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