{"record":{"id":"4e4dc7c9b5302d10","repo":"Pumpkin-MC/Pumpkin","slug":"the-root-tag-of-the-nbt-file-is-not-a-compound-tag","errorCode":null,"errorMessage":"The root tag of the NBT file is not a compound tag. Received tag id: {0}","messagePattern":"The root tag of the NBT file is not a compound tag\\. Received tag id: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/pumpkin-nbt/src/lib.rs","lineNumber":74,"sourceCode":"/// Numeric identifier for a list tag.\npub const LIST_ID: u8 = 0x09;\n/// Numeric identifier for a compound tag.\npub 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}\")]","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/Pumpkin-MC/Pumpkin/blob/8d4639e25a57c15e47448ec327c780d41bbf2356/crates/pumpkin-nbt/src/lib.rs#L56-L92","documentation":"Error::NoRootCompound(u8) is raised when decoding an NBT document whose root tag is not a compound (tag id 0x0A). The NBT crate requires a named root compound for full Nbt documents, so it reports the tag id it actually received. This typically means the bytes are not a valid NBT file, are compressed differently than assumed, or the stream is offset.","triggerScenarios":"Calling Nbt::read/from_reader on data whose first tag id byte is not 0x0A; reading gzip data that is not actually gzipped (wrong first bytes); decoding a network/Bedrock payload with the wrong NBT variant (Java vs network vs Bedrock); reading a raw NbtTag where an Nbt document was expected.","commonSituations":"Loading a .dat/.schematic file that is uncompressed or zlib instead of gzip; pointing a reader at a misaligned offset in a container format; a version change where Minecraft switched root representation; passing network little-endian NBT to the Java reader.","solutions":["Check the first byte(s) of your data: gzip magic 0x1F 0x8B means compressed; wrap the reader in GzDecoder/FlateDecoder as appropriate before parsing.","Confirm you are using the matching reader variant (Java disk NBT vs network NBT vs Bedrock network NBT) for your data source.","Verify you are at offset 0 of the NBT document, not inside a wrapper format that prefixes other data.","If the payload is legitimately a non-compound root tag, parse it as NbtTag instead of Nbt."],"exampleFix":"// before\nlet nbt = Nbt::from_reader(&mut file)?;\n// after: detect gzip first\nlet mut reader = if is_gzip(&mut file)? { GzDecoder::new(file) } else { file };\nlet nbt = Nbt::from_reader(&mut reader)?;","handlingStrategy":"validation","validationCode":"// Rust: check gzip magic before decoding\nfn is_gzip(mut r: impl Read) -> std::io::Result<bool> {\n    let mut b = [0u8; 2];\n    r.read_exact(&mut b)?;\n    Ok(b == [0x1F, 0x8B])\n}","typeGuard":"fn root_is_compound(first_tag_id: u8) -> bool { first_tag_id == pumpkin_nbt::COMPOUND_ID }","tryCatchPattern":"match Nbt::from_reader(&mut reader) {\n    Err(pumpkin_nbt::Error::NoRootCompound(id)) => eprintln!(\"root tag id {id} - wrong format/compression?\"),\n    Err(e) => return Err(e.into()),\n    Ok(nbt) => nbt,\n}","preventionTips":["Always detect compression (gzip magic bytes) before constructing the reader","Match the NBT variant (Java/network/Bedrock) to the data source","Parse from offset 0 of the NBT document, skipping any container headers first"],"tags":["minecraft","nbt","serialization","decoding"],"backgroundTag":"schema-validation-failed","analyzedSha":"8d4639e25a57c15e47448ec327c780d41bbf2356","analyzedAt":"2026-09-09T15:32:22.916Z","contentChangedAt":"2026-09-09T15:32:22.916Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}