Pumpkin-MC/Pumpkin · error · Error

Encountered an unknown NBT tag id

Error message

Encountered an unknown NBT tag id: {0}.

What it means

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.

Solutions

1. Dump the offending byte and its offset; confirm it is a plausible NBT tag id (0x00-0x0C, see the *_ID constants in pumpkin-nbt).
2. Verify stream alignment: ensure all prior reads consumed exactly the right number of bytes (strings include a 2-byte or varint length).
3. Use the correct NBT variant decoder (Java vs Bedrock little-endian vs network unnamed) for your source.
4. Re-export or regenerate the data with a known-good tool to rule out file corruption.

Example fix

// before: assuming plain NBT from offset 0
let nbt = Nbt::from_reader(&mut cursor)?;
// after: skip the known header first
cursor.set_position(HEADER_LEN);
let nbt = Nbt::from_reader(&mut cursor)?;

// Rust: sanity-check tag ids against known constants
fn known_tag_id(id: u8) -> bool { id <= pumpkin_nbt::LONG_ARRAY_ID }

fn is_defined_tag(id: u8) -> bool { matches!(id, 0..=0x0C) }

match Nbt::from_reader(&mut reader) {
    Err(pumpkin_nbt::Error::UnknownTagId(id)) => eprintln!("unknown tag {id:#x} at offset {:?}", reader.stream_position()),
    Err(e) => return Err(e.into()),
    Ok(nbt) => nbt,
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Negative list length
• The root tag of the NBT file is not a compound tag…
• Failed to Cesu 8 Decode
• Failed to UTF-8 Decode
• Serde error

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

Appendix: source

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

pub const COMPOUND_ID: u8 = 0x0A;
/// Numeric identifier for an integer-array tag.
pub const INT_ARRAY_ID: u8 = 0x0B;
/// Numeric identifier for a long-array tag.
pub const LONG_ARRAY_ID: u8 = 0x0C;

/// Maximum number of elements accepted when decoding a list or array.
pub const MAX_ARRAY_LENGTH: usize = 512_000;
/// Maximum nesting depth allowed when decoding NBT compound or list tags.
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}")]

View on GitHub (pinned to 8d4639e25a)