Pumpkin-MC/Pumpkin · error · Error

Serde error

Error message

Serde error: {0}

What it means

Error::SerdeError(String) wraps an error reported by serde while converting NBT data to/from Rust types via the serde bridge. The library throws it when serde's deserializer rejects a value (wrong shape, missing field, invalid enum variant) or a serializer hits an invalid state. The inner string carries serde's own diagnostic message.

Solutions

1. Read the wrapped serde message: it names the failing field/value; align your struct definition with the actual NBT content.
2. Make optional fields Option<T> (or add #[serde(default)]) since missing NBT tags cannot populate required fields.
3. Verify numeric widths: NBT distinguishes byte/short/int/long; widen your Rust types or add serde conversions.
4. If decoding data from a different Minecraft version, regenerate the struct from a current example of the format.

Example fix

// before
struct Spawner { delay: i32 }
// after: field may be absent or a byte in some versions
#[derive(Deserialize)]
struct Spawner {
    #[serde(default)]
    delay: i32,
}

// Rust: probe the fields you depend on before full deserialization
fn has_field(c: &NbtCompound, key: &str) -> bool { c.contains_key(key) }

match MyStruct::from_nbt(compound) {
    Err(pumpkin_nbt::Error::SerdeError(msg)) => eprintln!("serde: {msg} - check struct fields"),
    Err(e) => return Err(e.into()),
    Ok(v) => v,
}

When it happens

Trigger: Deserializing an NbtCompound into a struct whose fields don't match the NBT data (missing/renamed fields, type mismatch like i32 vs i64); using serde(rename/flatten) attributes that conflict with NBT structure; serializing types serde cannot represent in the chosen NBT shape.

Common situations: World/version format changes where a field was renamed or its type widened; hand-written structs drifting from actual saved data; option handling — NBT has no distinct null so absent tags fail non-Option fields.

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

• NBT doesn't support this type
• Failed to parse chunk from bytes
• The root tag of the NBT file is not a compound tag…
• Encountered an unknown NBT tag id
• Failed to Cesu 8 Decode

AI-assisted analysis of Pumpkin-MC/Pumpkin@8d4639e25a (2026-09-09). Data as JSON: /api/errors/ce31e1432aa29e23. Report an issue: GitHub.

Appendix: source

Thrown at crates/pumpkin-nbt/src/lib.rs:86

pub const MAX_NBT_DEPTH: usize = 512;

/// Errors produced while reading, writing, or converting NBT data.
#[derive(Error, Debug)]
pub enum Error {
    /// The root tag was not a compound tag and contains the reported tag ID.
    #[error("The root tag of the NBT file is not a compound tag. Received tag id: {0}")]
    NoRootCompound(u8),
    /// A tag ID not defined by the NBT format was encountered.
    #[error("Encountered an unknown NBT tag id: {0}.")]
    UnknownTagId(u8),
    /// A Java CESU-8 string could not be decoded.
    #[error("Failed to Cesu 8 Decode")]
    Cesu8DecodingError,
    /// A string could not be decoded as UTF-8.
    #[error("Failed to UTF-8 Decode")]
    Utf8DecodingError,
    /// Serde reported an invalid value or serializer state.
    #[error("Serde error: {0}")]
    SerdeError(String),
    /// The requested Rust type has no NBT representation.
    #[error("NBT doesn't support this type: {0}")]
    UnsupportedType(String),
    /// The underlying reader or writer returned an I/O error.
    #[error("NBT reading was cut short: {0}")]
    Incomplete(io::Error),
    /// A list or array declared a negative element count.
    #[error("Negative list length: {0}")]
    NegativeLength(i32),
    /// A string, list, or array exceeded the supported length.
    #[error("Length too large: {0}")]
    LargeLength(usize),
    /// A Bedrock variable-length integer exceeded its maximum encoded size.
    #[error("Failed to decode varint - value too large")]
    VarIntTooLarge,
    /// A Bedrock variable-length long exceeded its maximum encoded size.
    #[error("Failed to decode varlong - value too large")]

View on GitHub (pinned to 8d4639e25a)