nautechsystems/nautilus_trader · error

unknown broker client order ID signal byte

Error message

unknown broker client order ID signal byte '{}'

What it means

During decoding of a Binance broker client order ID, the first byte after the broker prefix (the 'signal' byte) did not match any known format tag (e.g. SIGNAL_O_HYPHENS, SIGNAL_O_NO_HYPHENS, raw payload). The decoder bails, reporting the offending byte as a char. This means the ID was not produced (or not produced intact) by this adapter's encoder.

Solutions

  1. Do not decode IDs not produced by this encoder — pass the exchange ID through unchanged or treat it as an opaque string.
  2. Align encoder/decoder versions: regenerate the ID with the current adapter version and resubmit.
  3. If constructing IDs manually, use the adapter's encode function rather than prepending the prefix yourself.
  4. Log the full offending ID and compare against encoder output to identify where the signal byte was lost or altered.

Example fix

// before
let decoded = decode_client_order_id(raw_id)?; // bails on foreign-format IDs
// after
let decoded = match decode_client_order_id(raw_id) {
    Ok(id) => id,
    Err(_) => raw_id.to_string(), // treat as opaque passthrough
};
Defensive patterns

Strategy: fallback

Validate before calling

fn looks_like_encoded_broker_id(id: &str, prefix: &str) -> bool {
    id.strip_prefix(prefix)
        .map_or(false, |p| p.as_bytes().first().is_some_and(|b| is_known_signal(*b)))
}

Try / catch

let client_id = match decode_client_order_id(exchange_id) {
    Ok(id) => id,
    Err(e) if e.to_string().contains("unknown broker client order ID signal") =>
        exchange_id.to_string(), // opaque passthrough
    Err(e) => return Err(e),
};

Prevention

When it happens

Trigger: Calling decode_broker_id / decode_client_order_id on an ID whose payload's first byte is unrecognized — IDs created by a different encoder version, manually constructed IDs with the broker prefix prepended, or bit-corrupted payloads.

Common situations: Mixing client order IDs across adapter versions after an encoder format change; manually prefixing a plain UUID with the broker prefix expecting the decoder to accept it; copy/paste or transport corruption of the ID string.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at crates/adapters/binance/src/common/encoder.rs:263

            Ok(unpack_o_format(packed, signal == SIGNAL_O_HYPHENS))
        }
        SIGNAL_UUID_HYPHENS | SIGNAL_UUID_NO_HYPHENS => {
            anyhow::ensure!(
                data.len() == UUID_B62_LEN,
                "invalid UUID broker client order ID payload length"
            );
            let value = decode_base62(data).context("invalid UUID broker client order ID")?;
            Ok(format_uuid(value, signal == SIGNAL_UUID_HYPHENS))
        }
        SIGNAL_RAW => {
            let raw = std::str::from_utf8(data).context("invalid raw broker client order ID")?;
            anyhow::ensure!(
                !raw.is_empty(),
                "missing raw broker client order ID payload"
            );
            Ok(raw.to_string())
        }
        _ => anyhow::bail!(
            "unknown broker client order ID signal byte '{}'",
            signal as char
        ),
    }
}

fn build_encoded(prefix: &str, signal: u8, b62: &[u8]) -> String {
    let mut result = String::with_capacity(prefix.len() + 1 + b62.len());
    result.push_str(prefix);
    result.push(signal as char);
    // base62 output is always valid ASCII
    result.push_str(std::str::from_utf8(b62).expect("base62 is valid UTF-8"));
    result
}

fn encode_base62<const N: usize>(mut value: u128) -> [u8; N] {
    let mut buf = [b'0'; N];
    for i in (0..N).rev() {

View on GitHub (pinned to 18893faf8b)