{"record":{"id":"36ea95dc5fc1a4a6","repo":"nautechsystems/nautilus_trader","slug":"unknown-broker-client-order-id-signal-byte","errorCode":null,"errorMessage":"unknown broker client order ID signal byte '{}'","messagePattern":"unknown broker client order ID signal byte '(.+?)'","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/binance/src/common/encoder.rs","lineNumber":263,"sourceCode":"            Ok(unpack_o_format(packed, signal == SIGNAL_O_HYPHENS))\n        }\n        SIGNAL_UUID_HYPHENS | SIGNAL_UUID_NO_HYPHENS => {\n            anyhow::ensure!(\n                data.len() == UUID_B62_LEN,\n                \"invalid UUID broker client order ID payload length\"\n            );\n            let value = decode_base62(data).context(\"invalid UUID broker client order ID\")?;\n            Ok(format_uuid(value, signal == SIGNAL_UUID_HYPHENS))\n        }\n        SIGNAL_RAW => {\n            let raw = std::str::from_utf8(data).context(\"invalid raw broker client order ID\")?;\n            anyhow::ensure!(\n                !raw.is_empty(),\n                \"missing raw broker client order ID payload\"\n            );\n            Ok(raw.to_string())\n        }\n        _ => anyhow::bail!(\n            \"unknown broker client order ID signal byte '{}'\",\n            signal as char\n        ),\n    }\n}\n\nfn build_encoded(prefix: &str, signal: u8, b62: &[u8]) -> String {\n    let mut result = String::with_capacity(prefix.len() + 1 + b62.len());\n    result.push_str(prefix);\n    result.push(signal as char);\n    // base62 output is always valid ASCII\n    result.push_str(std::str::from_utf8(b62).expect(\"base62 is valid UTF-8\"));\n    result\n}\n\nfn encode_base62<const N: usize>(mut value: u128) -> [u8; N] {\n    let mut buf = [b'0'; N];\n    for i in (0..N).rev() {","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/a4b06ed870971b5671d12754ea138a3ab99b1dec/crates/adapters/binance/src/common/encoder.rs#L245-L281","documentation":"Decoding a broker-prefixed client order ID: the first byte after the prefix must be one of the known signal bytes (O-format, UUID, or raw variants). The observed byte matches none of them, so the payload format is unrecognizable.","triggerScenarios":"Any clientOrderId that starts with the broker prefix but continues with a byte the encoder never emits - foreign exchange-generated IDs, user-supplied IDs, or a payload format introduced in a newer adapter version than the decoder.","commonSituations":"Broker prefix configured so short (1-2 chars) that Binance's own appended IDs (e.g. autoclose/conditional suffixes) begin with it; reading orders created by a newer adapter; hand-built IDs.","solutions":["Configure a longer, distinctive broker_id so unrelated IDs never share the prefix","Upgrade the reading side to the adapter version that produced the IDs (new signal bytes appear with format extensions)","If the ID genuinely is not yours, treat it as an opaque external ID instead of decoding"],"exampleFix":"// before\nmatch decode_broker_id_checked(encoded, broker_id) {\n    Ok(cid) => cid,\n    Err(e) => return Err(e),\n}\n\n// after: unknown signal -> opaque raw ID, keep processing updates\nlet cid = decode_broker_id_checked(encoded, broker_id)\n    .unwrap_or_else(|_| encoded.to_string());","handlingStrategy":"fallback","validationCode":"const KNOWN_SIGNALS: &[u8] = b\"oOuUw\"; // however the adapter spells them - mirror encoder constants\nfn has_known_signal(id: &str, prefix: &str) -> bool {\n    id.strip_prefix(prefix)\n        .and_then(|p| p.as_bytes().first())\n        .is_none_or(|b| KNOWN_SIGNALS.contains(b))\n}","typeGuard":"fn is_adapter_generated_id(id: &str, prefix: &str) -> bool {\n    id.strip_prefix(prefix)\n        .and_then(|p| p.as_bytes().first())\n        .is_some_and(|b| KNOWN_SIGNALS.contains(b))\n}","tryCatchPattern":"let cid = match decode_broker_id_checked(encoded, broker_id) {\n    Ok(decoded) => ClientOrderId::new_checked(decoded)?,\n    Err(_) => {\n        // unknown signal -> assume foreign exchange-generated ID, use verbatim\n        ClientOrderId::new(encoded)\n    }\n};","preventionTips":["Prefer long unique broker IDs over short defaults","When reading orders back from Binance, accept that exchange-appended IDs may not be yours and handle them opaquely","Keep encoder and decoder in the same crate version - new signal bytes only exist in newer versions"],"tags":["binance","order-ids","client-order-id","signal-byte","encoding"],"backgroundTag":"identifier-decode-failed","analyzedSha":"a4b06ed870971b5671d12754ea138a3ab99b1dec","analyzedAt":"2026-08-16T22:54:50.089Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}