nautechsystems/nautilus_trader · error

Unknown payload kind '{value}'

Error message

Unknown payload kind '{value}'

What it means

The stream entry declares a payload-kind header, but its value is not the recognized typed constant (PAYLOAD_KIND_TYPED). The decoder uses anyhow::ensure! to reject any other kind string, since the wire protocol only defines that one value.

Source

Thrown at crates/infrastructure/src/redis/msgbus.rs:853

                );
            }
            b"type" => {
                let redis::Value::BulkString(bytes) = &pair[1] else {
                    anyhow::bail!("Invalid type format: {stream_msg:?}");
                };
                type_name = Some(
                    String::from_utf8(bytes.clone())
                        .map_err(|e| anyhow::anyhow!("Error parsing type: {e}"))?,
                );
            }
            key if key == PAYLOAD_KIND_FIELD.as_bytes() => {
                let redis::Value::BulkString(bytes) = &pair[1] else {
                    anyhow::bail!("Invalid payload kind format: {stream_msg:?}");
                };
                let value = std::str::from_utf8(bytes)
                    .map_err(|e| anyhow::anyhow!("Error parsing payload kind: {e}"))?;
                anyhow::ensure!(
                    value == PAYLOAD_KIND_TYPED,
                    "Unknown payload kind '{value}'"
                );
                typed_payload = true;
            }
            b"encoding" => {
                let redis::Value::BulkString(bytes) = &pair[1] else {
                    anyhow::bail!("Invalid encoding format: {stream_msg:?}");
                };
                let value = std::str::from_utf8(bytes)
                    .map_err(|e| anyhow::anyhow!("Error parsing encoding: {e}"))?;
                encoding = value
                    .parse()
                    .map_err(|e| anyhow::anyhow!("Error parsing encoding: {e}"))?;
            }
            b"payload" => {
                let redis::Value::BulkString(bytes) = &pair[1] else {
                    anyhow::bail!("Invalid payload format: {stream_msg:?}");
                };

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Align producer and consumer versions so both agree on the supported payload kind value.
  2. Fix the published entry to use the exact expected kind constant, or omit the kind header for untyped payloads.
  3. Check for typos or case differences in the kind value in the stream entry.
  4. Upgrade the consumer library if the producer intentionally uses a newer kind this version cannot parse.

Example fix

// before
XADD bus * topic "q" kind "typd"
// after (exact constant)
XADD bus * topic "q" kind "typed"
Defensive patterns

Strategy: validation

Validate before calling

// Only publish the exact supported kind constant (or omit kind entirely)
const PAYLOAD_KIND_TYPED: &str = "typed";
assert!(kind == PAYLOAD_KIND_TYPED || kind.is_empty(), "unsupported payload kind: {kind}");

Type guard

fn known_kind(v: &str, expected: &str) -> bool { v == expected }

Try / catch

match stream_messages(&mut con, stream, count).await {
    Ok(msgs) => { /* use msgs */ }
    Err(e) if e.to_string().starts_with("Unknown payload kind") => {
        // upgrade consumer or reject producer version
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: decode_bus_message reads an entry whose payload-kind field contains any string other than the expected PAYLOAD_KIND_TYPED — e.g. a typo, a future/newer producer using a new kind value that this consumer version does not know, or a manually written kind.

Common situations: Producer and consumer version mismatch (new kind introduced upstream, old consumer); typos in hand-crafted test entries; another application reusing the stream with its own kind vocabulary.

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

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