{"record":{"id":"7a0bbdaabc25dccc","repo":"Pumpkin-MC/Pumpkin","slug":"failed-to-cesu-8-decode","errorCode":null,"errorMessage":"Failed to Cesu 8 Decode","messagePattern":"Failed to Cesu 8 Decode","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/pumpkin-nbt/src/lib.rs","lineNumber":80,"sourceCode":"/// Numeric identifier for a long-array tag.\npub const LONG_ARRAY_ID: u8 = 0x0C;\n\n/// Maximum number of elements accepted when decoding a list or array.\npub const MAX_ARRAY_LENGTH: usize = 512_000;\n/// Maximum nesting depth allowed when decoding NBT compound or list tags.\npub const MAX_NBT_DEPTH: usize = 512;\n\n/// Errors produced while reading, writing, or converting NBT data.\n#[derive(Error, Debug)]\npub enum Error {\n    /// The root tag was not a compound tag and contains the reported tag ID.\n    #[error(\"The root tag of the NBT file is not a compound tag. Received tag id: {0}\")]\n    NoRootCompound(u8),\n    /// A tag ID not defined by the NBT format was encountered.\n    #[error(\"Encountered an unknown NBT tag id: {0}.\")]\n    UnknownTagId(u8),\n    /// A Java CESU-8 string could not be decoded.\n    #[error(\"Failed to Cesu 8 Decode\")]\n    Cesu8DecodingError,\n    /// A string could not be decoded as UTF-8.\n    #[error(\"Failed to UTF-8 Decode\")]\n    Utf8DecodingError,\n    /// Serde reported an invalid value or serializer state.\n    #[error(\"Serde error: {0}\")]\n    SerdeError(String),\n    /// The requested Rust type has no NBT representation.\n    #[error(\"NBT doesn't support this type: {0}\")]\n    UnsupportedType(String),\n    /// The underlying reader or writer returned an I/O error.\n    #[error(\"NBT reading was cut short: {0}\")]\n    Incomplete(io::Error),\n    /// A list or array declared a negative element count.\n    #[error(\"Negative list length: {0}\")]\n    NegativeLength(i32),\n    /// A string, list, or array exceeded the supported length.\n    #[error(\"Length too large: {0}\")]","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/Pumpkin-MC/Pumpkin/blob/8d4639e25a57c15e47448ec327c780d41bbf2356/crates/pumpkin-nbt/src/lib.rs#L62-L98","documentation":"Error::Cesu8DecodingError is raised when a string payload in the NBT data cannot be decoded as Java CESU-8 (the modified UTF-8 Minecraft/Java uses, where U+0000 is encoded as 0xC0 0x80 and supplementary characters as surrogate pairs). The library throws it because the byte sequence violates CESU-8 encoding rules and cannot be converted losslessly.","triggerScenarios":"Decoding an NBT string tag whose length-prefixed bytes are not valid CESU-8 (e.g., truncated multi-byte sequence, lone surrogate, or standard UTF-8-encoded supplementary character from a non-Java writer); a length prefix that cuts a character in half due to stream misalignment.","commonSituations":"Data written by non-Java NBT libraries that emit standard UTF-8 instead of Java's modified UTF-8; corrupted files where a string length was misread; network data desynchronized so the length covers only part of a string.","solutions":["Verify the string length prefix was read correctly (unsigned short for Java NBT) — a misread length is the most common cause.","Check the producing tool: if it writes standard UTF-8 rather than Java modified UTF-8, convert/normalize the data or use a decoder variant that accepts UTF-8.","Scan the bytes for invalid sequences (0xC0 0x80 is valid CESU-8; truncated 0x8x continuation bytes are not) to locate corruption.","If the source is external, transcode strings to CESU-8 before embedding them in NBT."],"exampleFix":"// before: writing plain Rust strings via a generic UTF-8 writer\nwriter.write_str(s)?; // standard UTF-8, supplementary chars not surrogate-paired\n// after: encode as Java modified UTF-8\nlet cesu = to_java_modified_utf8(s);\nwriter.write_str(&cesu)?;","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match Nbt::from_reader(&mut reader) {\n    Err(pumpkin_nbt::Error::Cesu8DecodingError) => eprintln!(\"non-CESU-8 string in NBT; check the writer\"),\n    Err(e) => return Err(e.into()),\n    Ok(nbt) => nbt,\n}","preventionTips":["Ensure tools writing your NBT encode strings as Java modified UTF-8 (CESU-8)","Verify string length prefixes are read as big-endian u16 for Java NBT","Round-trip a known file as a regression test for your encode/decode path"],"tags":["minecraft","nbt","encoding","cesu8"],"backgroundTag":"invalid-argument-format","analyzedSha":"8d4639e25a57c15e47448ec327c780d41bbf2356","analyzedAt":"2026-09-09T15:32:22.916Z","contentChangedAt":"2026-09-09T15:32:22.916Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}