{"record":{"id":"c2f4e72790442640","repo":"Pumpkin-MC/Pumpkin","slug":"encountered-an-unknown-nbt-tag-id-0","errorCode":null,"errorMessage":"Encountered an unknown NBT tag id: {0}.","messagePattern":"Encountered an unknown NBT tag id: (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/pumpkin-nbt/src/lib.rs","lineNumber":77,"sourceCode":"pub const COMPOUND_ID: u8 = 0x0A;\n/// Numeric identifier for an integer-array tag.\npub const INT_ARRAY_ID: u8 = 0x0B;\n/// 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}\")]","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/Pumpkin-MC/Pumpkin/blob/8d4639e25a57c15e47448ec327c780d41bbf2356/crates/pumpkin-nbt/src/lib.rs#L59-L95","documentation":"Error::UnknownTagId(u8) is raised while reading NBT when a tag type byte is encountered that is not one of the defined NBT ids (0x00-0x0C). The library throws it because it cannot know how to decode the following payload. It almost always indicates corrupted data, a wrong offset, or parsing with the wrong NBT dialect.","triggerScenarios":"A payload byte stream contains a tag id > 0x0C or an invalid id where a tag is expected; reading at a wrong offset so arbitrary data is interpreted as a tag id; feeding Bedrock/Java-flavored NBT to the wrong decoder; truncated or corrupted files.","commonSituations":"Hand-edited or corrupted world files; custom binary formats that prepend headers being parsed as NBT directly; network desync where the reader starts mid-payload; third-party tools writing nonstandard tag ids.","solutions":["Dump the offending byte and its offset; confirm it is a plausible NBT tag id (0x00-0x0C, see the *_ID constants in pumpkin-nbt).","Verify stream alignment: ensure all prior reads consumed exactly the right number of bytes (strings include a 2-byte or varint length).","Use the correct NBT variant decoder (Java vs Bedrock little-endian vs network unnamed) for your source.","Re-export or regenerate the data with a known-good tool to rule out file corruption."],"exampleFix":"// before: assuming plain NBT from offset 0\nlet nbt = Nbt::from_reader(&mut cursor)?;\n// after: skip the known header first\ncursor.set_position(HEADER_LEN);\nlet nbt = Nbt::from_reader(&mut cursor)?;","handlingStrategy":"validation","validationCode":"// Rust: sanity-check tag ids against known constants\nfn known_tag_id(id: u8) -> bool { id <= pumpkin_nbt::LONG_ARRAY_ID }","typeGuard":"fn is_defined_tag(id: u8) -> bool { matches!(id, 0..=0x0C) }","tryCatchPattern":"match Nbt::from_reader(&mut reader) {\n    Err(pumpkin_nbt::Error::UnknownTagId(id)) => eprintln!(\"unknown tag {id:#x} at offset {:?}\", reader.stream_position()),\n    Err(e) => return Err(e.into()),\n    Ok(nbt) => nbt,\n}","preventionTips":["Never parse a binary blob as NBT without confirming its container/offset","Use the matching dialect decoder (Java vs Bedrock vs network)","Log byte offsets on failure to detect stream misalignment early"],"tags":["minecraft","nbt","decoding","corrupt-data"],"backgroundTag":"invalid-enum-value","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"}