Pumpkin-MC/Pumpkin · error · TemplateError

Failed to decompress NBT

Error message

Failed to decompress NBT: {0}

What it means

Variant `NbtError` of `TemplateError` in pumpkin-world's structure template loader, auto-converted from `pumpkin_nbt::Error`. It is thrown when loading (decompressing/parsing) a structure template NBT fails — typically a `.nbt` structure file read during jigsaw/structure placement.

Solutions

1. Verify the structure file is valid compressed NBT (test with an NBT viewer)
2. Re-export the structure from the same Minecraft version the server targets
3. Replace the corrupted template file in the world/datapack

Example fix

// before: assuming file is valid NBT
let nbt = pumpkin_nbt::from_reader(&mut file)?;
// after: guard with an existence/format check first
if file.metadata()?.len() == 0 { return Err(TemplateError::NbtError(...)); }
let nbt = pumpkin_nbt::from_reader(&mut file)?;

let meta = std::fs::metadata(path)?;
if meta.len() == 0 { return Err("empty structure template".into()); }
let magic = std::fs::read(path)?.get(..2).map(|b| b.as_ref());
if magic != Some(&[0x1f, 0x8b]) { return Err("not gzip-compressed NBT".into()); }

fn looks_like_gzip_nbt(bytes: &[u8]) -> bool { bytes.starts_with(&[0x1f, 0x8b]) }

match StructureTemplate::load(path) {
    Err(TemplateError::NbtError(e)) => error!("invalid structure NBT at {path}: {e}"),
    other => other?,
}

When it happens

Trigger: Loading a structure template file whose NBT payload cannot be decompressed or parsed (bad gzip/NBT header, truncated file).

Common situations: Structure files exported by third-party tools in the wrong format, corrupted resource-pack/datapack structure files, text files saved as `.nbt` without compression.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Deserialization error
• Error deserializing chunk
• Failed reading chunk status
• Failed to decode varint - value too large
• Failed to decode varlong - value too large

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

Appendix: source

Thrown at crates/pumpkin-world/src/generation/structure/template/structure_template.rs:19

//! Structure template loading, transformation, and saving (1:1 matching Minecraft vanilla `StructureTemplate`).
//!
//! This module handles parsing vanilla Minecraft structure template files (`.nbt`)
//! into a runtime representation with palettes, entities, block info, and transformations.

use std::io::Cursor;

use pumpkin_data::{Mirror, Rotation};
use pumpkin_nbt::{compound::NbtCompound, nbt_compress::read_gzip_compound_tag, tag::NbtTag};
use pumpkin_util::math::{block_box::BlockBox, vector3::Vector3};
use thiserror::Error;

use super::processor::StructureProcessor;
use crate::generation::structure::structures::jigsaw::JigsawJointType;

/// Errors that can occur when loading or saving a structure template.
#[derive(Debug, Error)]
pub enum TemplateError {
    #[error("Failed to decompress NBT: {0}")]
    NbtError(#[from] pumpkin_nbt::Error),

    #[error("Missing required field: {0}")]
    MissingField(&'static str),

    #[error("Invalid field type for {0}")]
    InvalidFieldType(&'static str),

    #[error("Invalid palette index: {0}")]
    InvalidPaletteIndex(u32),
}

/// Settings used when placing, transforming, or querying a [`StructureTemplate`].
#[derive(Clone, Debug)]
pub struct StructurePlaceSettings {
    pub mirror: Mirror,
    pub rotation: Rotation,
    pub rotation_pivot: Vector3<i32>,

View on GitHub (pinned to 8d4639e25a)