{"record":{"id":"d869804b5da71053","repo":"Pumpkin-MC/Pumpkin","slug":"failed-to-utf-8-decode","errorCode":null,"errorMessage":"Failed to UTF-8 Decode","messagePattern":"Failed to UTF-8 Decode","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/pumpkin-nbt/src/lib.rs","lineNumber":83,"sourceCode":"/// 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}\")]\n    LargeLength(usize),\n    /// A Bedrock variable-length integer exceeded its maximum encoded size.\n    #[error(\"Failed to decode varint - value too large\")]","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/Pumpkin-MC/Pumpkin/blob/8d4639e25a57c15e47448ec327c780d41bbf2356/crates/pumpkin-nbt/src/lib.rs#L65-L101","documentation":"Error::Utf8DecodingError is raised when a string in the NBT payload is not valid UTF-8 (this crate uses this for strings decoded as plain UTF-8, e.g., in Bedrock/network paths). The library throws it because Rust strings must be valid UTF-8 and the raw bytes fail validation. It indicates corrupted data, a wrong length read, or a dialect mismatch.","triggerScenarios":"A string tag's bytes fail std::str::from_utf8 validation; the length prefix was misread so a multi-byte character is split; reading Java CESU-8 supplementary characters (surrogate 0xED A0-xx sequences) through the strict UTF-8 path; random binary parsed as a string due to offset error.","commonSituations":"Mixing Java and Bedrock NBT decoders; files truncated mid-string; custom NBT writers that emit non-UTF-8 bytes; desynchronized network streams.","solutions":["Confirm you are using the decoder variant matching the data (Java CESU-8 strings vs Bedrock UTF-8 strings).","Check the length prefix parsing: Java uses big-endian u16, Bedrock uses a varint — mixing these shifts/cuts strings.","Validate the raw bytes at the reported offset with String::from_utf8 in a test to see the exact failing byte index.","Repair or re-export the source file if the bytes are genuinely corrupted."],"exampleFix":"// before: Java reader applied to Bedrock data\nlet nbt = Nbt::from_reader(&mut bedrock_stream)?;\n// after\nlet nbt = Nbt::from_reader_bedrock(&mut bedrock_stream)?;","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match Nbt::from_reader(&mut reader) {\n    Err(pumpkin_nbt::Error::Utf8DecodingError) => eprintln!(\"invalid UTF-8 string; dialect or corruption issue\"),\n    Err(e) => return Err(e.into()),\n    Ok(nbt) => nbt,\n}","preventionTips":["Use the Bedrock reader for little-endian/UTF-8 data and the Java reader for CESU-8 data","Check for file truncation when many strings fail at once","Validate raw bytes with String::from_utf8 when debugging a specific string"],"tags":["minecraft","nbt","encoding","utf8"],"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"}