nautechsystems/nautilus_trader · error · anyhow::Error

missing broker client order ID signal

Error message

missing broker client order ID signal

What it means

The Binance adapter packs NautilusTrader ClientOrderIds into Binance's clientOrderId as broker_id prefix + one signal byte + base62 payload. On decode, after stripping the configured broker prefix nothing remained, so there is no signal byte to dispatch on and the ID cannot be unpacked.

Source

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

/// Returns an error if the broker-prefixed encoding is malformed or the
/// decoded client order ID is invalid.
pub(crate) fn decode_client_order_id(
    encoded: &str,
    broker_id: &str,
) -> anyhow::Result<ClientOrderId> {
    let decoded = decode_broker_id_checked(encoded, broker_id)?;
    ClientOrderId::new_checked(decoded)
        .with_context(|| format!("invalid Binance client order ID '{encoded}'"))
}

fn decode_broker_id_checked(encoded: &str, broker_id: &str) -> anyhow::Result<String> {
    let prefix = broker_prefix(broker_id);
    let Some(payload) = encoded.strip_prefix(&prefix) else {
        return Ok(encoded.to_string());
    };

    let Some((&signal, data)) = payload.as_bytes().split_first() else {
        anyhow::bail!("missing broker client order ID signal");
    };

    match signal {
        SIGNAL_O_HYPHENS | SIGNAL_O_NO_HYPHENS => {
            anyhow::ensure!(
                data.len() == O_FORMAT_B62_LEN,
                "invalid O-format broker client order ID payload length"
            );
            let packed = decode_base62(data).context("invalid O-format broker client order ID")?;
            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))

View on GitHub (pinned to a4b06ed870)

Solutions

1. Configure a longer, distinctive BinanceBrokerId so exchange- or user-generated IDs never equal or start with the prefix
2. Do not hand-craft client_order_id values beginning with the broker prefix - let the adapter's encoder generate them
3. If decoding IDs stored externally, verify they were not truncated when saved to Binance (length limits apply)

Example fix

# before
broker_id = "BNB"          # short prefix, collisions likely

# after
broker_id = "NAUTILUS001"  # distinctive prefix

fn is_decodable_broker_id(id: &str, prefix: &str) -> bool {
    let Some(payload) = id.strip_prefix(prefix) else { return true }; // foreign IDs pass through
    !payload.is_empty() // a signal byte must remain
}

fn broker_id_has_signal(id: &str, prefix: &str) -> bool {
    id.strip_prefix(prefix).is_none_or(|p| !p.is_empty())
}

let cid = match decode_broker_id_checked(encoded, broker_id) {
    Ok(decoded) => ClientOrderId::new_checked(decoded)?,
    Err(e) => {
        log::warn!("treating '{encoded}' as opaque external ID: {e}");
        ClientOrderId::new(encoded)
    }
};

When it happens

Trigger: A clientOrderId that is byte-for-byte identical to the broker prefix (e.g. a short/generic BinanceBrokerId with an ID that happens to equal it), or an ID truncated/corrupted down to just the prefix.

Common situations: Custom user-supplied client_order_id values that begin with or equal the broker prefix; a broker_id configured as a very short string so foreign exchange-generated IDs collide with it; IDs persisted externally and truncated to fit Binance's length cap.

Related errors

• missing raw broker client order ID payload
• invalid O-format broker client order ID payload length
• invalid UUID broker client order ID payload length
• unknown broker client order ID signal byte '{}'
• {standard_key_var} not found in config or environment

AI-assisted analysis of nautechsystems/nautilus_trader@a4b06ed870 (2026-08-16). Data as JSON: /api/errors/aab728af78d3a67b. Report an issue: GitHub.