Pumpkin-MC/Pumpkin · error · TemplateError

Invalid palette index

Error message

Invalid palette index: {0}

What it means

TemplateError::InvalidPaletteIndex(u32) is a variant of TemplateError indicating that a block in a structure template references a palette index that does not exist in the loaded palette. The payload is the offending index. It exists so template loading can fail loudly instead of silently placing wrong blocks.

Solutions

1. Fix the template's 'state' values so each is within 0..palette_len-1; regenerate the template from a structure block if unsure.
2. If generating templates programmatically, look up each block state's palette index from the palette you built instead of hardcoding indices.
3. Validate all block 'state' values against the palette size before calling load.
4. As a defensive caller, treat the air-fallback behavior as a silent corruption signal and validate templates separately.

Example fix

// before: hardcoded index that may not exist
compound.put_int("state", 7);
// after: index resolved from the palette you wrote
let idx = palette_index_for_state(&palette, &state);
compound.put_int("state", idx as i32);

fn palette_indices_valid(nbt: &NbtCompound) -> bool {
    let palette_len = nbt.get_list("palette").map(|p| p.len())
        .or_else(|| nbt.get_list("palettes").and_then(|ps| ps.first()).and_then(|p| if let NbtTag::List(l) = p { Some(l.len()) } else { None }))
        .unwrap_or(0);
    nbt.get_list("blocks").map(|blocks| blocks.iter().all(|b| {
        b.get_compound("state").is_none() &&
        b.get_int("state").map(|s| (s as usize) < palette_len).unwrap_or(false)
    })).unwrap_or(true)
}

fn valid_state_index(idx: i32, palette_len: usize) -> bool {
    idx >= 0 && (idx as usize) < palette_len
}

match template.load(&compound) {
    Err(TemplateError::InvalidPaletteIndex(idx)) => eprintln!("block references palette index {idx} which does not exist"),
    Err(e) => return Err(e),
    Ok(()) => {}
}

When it happens

Trigger: During StructureTemplate::load/load_palette, a block entry's 'state' integer points past the end of the palette list (state index >= palette.len()). Note the current load path in this codebase falls back to minecraft:air via palette.state_for, so this variant primarily surfaces when palette index validation is enforced or in downstream placement code.

Common situations: Templates whose 'blocks' list was edited without updating palette indices; off-by-one or 1-based vs 0-based index mistakes in custom template generators; truncated palettes after manual NBT editing.

Related errors

• Invalid field type for
• Chunk serializing error
• Deserialization error
• Encountered an unknown NBT tag id
• Error deserializing chunk

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

Appendix: source

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

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>,
    pub bounding_box: Option<BlockBox>,
    pub ignore_entities: bool,
    pub apply_waterlogging: bool,
    pub known_shape: bool,
    pub processors: Vec<StructureProcessor>,
    pub finalize_entities: bool,
    pub palette_index: Option<usize>,
}

View on GitHub (pinned to 8d4639e25a)