Pumpkin-MC/Pumpkin · error · Error

NBT reading was cut short

Error message

NBT reading was cut short: {0}

What it means

Error::Incomplete(io::Error) is raised when the underlying reader or writer fails during NBT reading — the payload was cut short or I/O went wrong mid-parse. The library wraps the original std::io::Error so the root cause (UnexpectedEof, PermissionDenied, etc.) is preserved. It means the document is truncated or the source is unreadable, not that the NBT structure itself was invalid up to that point.

Solutions

  1. Inspect the inner io::Error kind: UnexpectedEof means truncation; PermissionDenied/other kinds point at the reader environment.
  2. Verify the source's full length — re-download or restore the truncated file.
  3. For network data, buffer the entire packet (or length-prefix reads) before handing the reader to the NBT decoder.
  4. Retry transient I/O errors only if the underlying source is retryable (network), not for files.

Example fix

// before: parsing before the payload is complete
let nbt = Nbt::from_reader(&mut partial_packet)?;
// after: wait for the full packet
let full = read_exact_packet(&mut stream)?;
let nbt = Nbt::from_reader(&mut full.as_slice())?;
Defensive patterns

Strategy: retry

Try / catch

match Nbt::from_reader(&mut reader) {
    Err(pumpkin_nbt::Error::Incomplete(io)) if io.kind() == ErrorKind::UnexpectedEof => {
        eprintln!("truncated NBT payload"); // buffer fully and retry once
    }
    Err(e) => return Err(e.into()),
    Ok(nbt) => nbt,
}

Prevention

When it happens

Trigger: Reading from a truncated file or a stream closed early; passing a reader that errors (disk failure, closed socket) mid-read; decoding a partial packet buffer where not all NBT bytes have arrived yet; reading network NBT from a buffer smaller than the document.

Common situations: World files truncated by a crash or incomplete download; async code reading a network NBT payload before the full packet arrives; file permission changes mid-session; reading from in-memory cursors built with the wrong slice length.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

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

    #[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}")]
    NegativeLength(i32),
    /// A string, list, or array exceeded the supported length.
    #[error("Length too large: {0}")]
    LargeLength(usize),
    /// A Bedrock variable-length integer exceeded its maximum encoded size.
    #[error("Failed to decode varint - value too large")]
    VarIntTooLarge,
    /// A Bedrock variable-length long exceeded its maximum encoded size.
    #[error("Failed to decode varlong - value too large")]
    VarLongTooLarge,
    /// NBT nesting depth exceeded the maximum allowed limit.
    #[error("NBT depth exceeded maximum allowed limit")]
    MaxDepthExceeded,
    /// A list tag specified an invalid element tag type.
    #[error("Invalid element tag type for list: {0}")]

View on GitHub (pinned to 8d4639e25a)