Pumpkin-MC/Pumpkin · error · ChunkReadingError

Invalid header

Error message

Invalid header

What it means

`ChunkReadingError::InvalidHeader` is raised when a chunk/region file's header does not match the expected format (a magic/structure check failed on read). It indicates the file is not a valid chunk/region file of the expected version.

Solutions

1. Verify the world format version matches what this server version expects
2. Regenerate or restore the region file from a backup
3. Check for empty/corrupt files (file size, hexdump the header bytes)
4. Re-run world conversion/migration tooling for format upgrades

Example fix

// before
let chunk = ChunkReader::read(path)?; // InvalidHeader on bad format
// after
match ChunkReader::read(path) {
    Ok(c) => c,
    Err(ChunkReadingError::InvalidHeader) => {
        log::warn!("bad chunk header at {path:?}; regenerating");
        regenerate_chunk();
    }
    Err(e) => return Err(e.into()),
}

// sanity-check the file before parsing
let meta = std::fs::metadata(&path)?;
if meta.len() < HEADER_SIZE { return Err(WorldError::BadRegionFile(path)); }

match chunk::read(&path) {
    Ok(c) => c,
    Err(ChunkReadingError::InvalidHeader) => {
        log::warn!("invalid header in {path:?}; regenerating chunk");
        regenerate_chunk();
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Reading a chunk file whose header bytes are wrong — empty file with only zeros, truncated header, or a file written by an incompatible world format version.

Common situations: Pointing the server at a world generated by a different version or another engine; partially written files after a crash; empty placeholder region files; user renamed/moved world files incorrectly.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Io error
• unexpected event
• unexpected event
• unexpected event
• Encountered an unknown NBT tag id

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

Appendix: source

Thrown at crates/pumpkin-world/src/chunk/mod.rs:32

use std::sync::atomic::AtomicBool;
use std::sync::atomic::AtomicU64;
use thiserror::Error;

pub mod format;
pub mod io;
pub mod palette;

// TODO
pub const CHUNK_WIDTH: usize = BlockPalette::SIZE;
pub const CHUNK_AREA: usize = CHUNK_WIDTH * CHUNK_WIDTH;
pub const BIOME_VOLUME: usize = BiomePalette::VOLUME;
pub const SUBCHUNK_VOLUME: usize = CHUNK_AREA * CHUNK_WIDTH;

#[derive(Error, Debug)]
pub enum ChunkReadingError {
    #[error("Io error: {0}")]
    IoError(std::io::Error),
    #[error("Invalid header")]
    InvalidHeader,
    #[error("Region is invalid")]
    RegionIsInvalid,
    #[error("Compression error {0}")]
    Compression(CompressionError),
    #[error("Tried to read chunk which does not exist")]
    ChunkNotExist,
    #[error("Failed to parse chunk from bytes: {0}")]
    ParsingError(ChunkParsingError),
}

#[derive(Error, Debug)]
pub enum ChunkWritingError {
    #[error("Io error: {0}")]
    IoError(std::io::Error),
    #[error("Compression error {0}")]
    Compression(CompressionError),
    #[error("Chunk serializing error: {0}")]

View on GitHub (pinned to 8d4639e25a)