nautechsystems/nautilus_trader · error

Failed to deserialize instrument payload

Error message

Failed to deserialize instrument payload

What it means

OKX WebSocket message parsing failed to deserialize an instrument payload received on an instruments/status channel. The library bails with anyhow when serde cannot turn the raw `data` JSON into the expected instrument type, aborting processing of that message.

Solutions

1. Log the raw message payload and compare it against the current OKX instruments channel schema in parse.rs
2. Update the deserialization structs/serde attributes in the OKX adapter to match the new OKX schema
3. Upgrade the nautilus_adapters/nautilus_trader package to a version with updated OKX parsing
4. Verify the message is actually routed to the correct channel parser (instruments vs event contracts)

Example fix

// before
anyhow::bail!("Failed to deserialize instrument payload")
// after
anyhow::bail!("Failed to deserialize instrument payload: {data:?}") // include payload for diagnosis; fix serde struct to match OKX schema

fn is_instrument_payload(msg: &serde_json::Value) -> bool {
    msg.get("data")
        .and_then(|d| d.as_array())
        .map(|a| a.iter().all(|o| o.get("instId").is_some()))
        .unwrap_or(false)
}

match parse_ws_message_data(msg) {
    Ok(Some(m)) => handle(m),
    Ok(None) => {},
    Err(e) => log::warn!("skip malformed OKX msg: {e}"),
}

When it happens

Trigger: An OKX WebSocket message on a channel mapping to OKXWsChannel::Instruments arrives whose `data` field cannot be deserialized into the expected instrument struct (e.g. OKX changed/added fields with incompatible types, message arrives with unexpected shape, or the wrong parser is used for the channel).

Common situations: OKX API schema updates introducing new field types; test fixtures or mocked payloads with malformed JSON; forwarding raw messages from endpoints (like event contract markets) that do not match the instrument schema.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Failed to deserialize Books channel data as Vec
• `api_key`, `api_secret`, `api_passphrase` credentials must…
• Authentication failed
• Authentication failed
• batch cancel orders failed

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

Appendix: source

Thrown at crates/adapters/okx/src/websocket/parse.rs:2410

                    maker_fee,
                    taker_fee,
                    ts_init,
                ) {
                    Ok(Some(inst_any)) => Ok(Some(NautilusWsMessage::Instrument(
                        Box::new(inst_any),
                        Some(status),
                    ))),
                    Ok(None) => {
                        log::warn!("Empty instrument payload: {msg:?}");
                        Ok(Some(NautilusWsMessage::InstrumentStatus(status)))
                    }
                    Err(e) => {
                        log::warn!("Failed to parse instrument {inst_key}: {e}");
                        Ok(Some(NautilusWsMessage::InstrumentStatus(status)))
                    }
                }
            } else {
                anyhow::bail!("Failed to deserialize instrument payload")
            }
        }
        OKXWsChannel::BboTbt => {
            let data_vec = parse_quote_msg_vec(
                data,
                instrument_id,
                price_precision,
                size_precision,
                ts_init,
            )?;
            Ok(Some(NautilusWsMessage::Data(data_vec)))
        }
        OKXWsChannel::Tickers => {
            let data_vec = parse_ticker_msg_vec(
                data,
                instrument_id,
                price_precision,
                size_precision,

View on GitHub (pinned to 18893faf8b)