Pumpkin-MC/Pumpkin · error · ChunkReadingError

Region is invalid

Error message

Region is invalid

What it means

ChunkReadingError::RegionIsInvalid is returned when an Anvil region file being read does not have a valid region file structure. The library throws it because the region header or region location data is malformed, so chunks in that region cannot be safely located or read.

Solutions

1. Verify the .mca region file is complete and uncorrupted (correct size, valid 8KiB header).
2. Restore the region file from a backup or regenerate the region with a Minecraft tool like MCASelector.
3. Check that the world directory layout and region file naming follow the Anvil format.
4. Catch this variant and treat the region as unreadable instead of crashing the server.

Example fix

// before: unwrap and crash on corrupt region
let chunk = reader.read_chunk(pos).unwrap();
// after
let chunk = match reader.read_chunk(pos) {
    Ok(c) => c,
    Err(ChunkReadingError::RegionIsInvalid) => { log::error!("corrupt region file; skipping"); return; }
    Err(e) => return Err(e),
};

let header = std::fs::read(&region_path)?;
if header.len() < 8192 { return Err("region file too small / truncated"); }

fn is_valid_region(file: &[u8]) -> bool { file.len() >= 8192 }

match reader.read_chunk(pos) {
    Err(ChunkReadingError::RegionIsInvalid) => skip_region(),
    other => other?,
}

When it happens

Trigger: Reading a chunk from a region file whose header (magic number / offsets table) is corrupt, truncated, or not actually a MCA region file.

Common situations: World files corrupted by crashes or disk issues, copying/partially downloading region files, pointing the world loader at a non-region file (e.g. a wrongly named or empty placeholder file).

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

• Compression error
• NBT reading was cut short
• Error while working with zlib compression
• Error while working with Gzip compression
• Unknown Status Code

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

Appendix: source

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

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}")]
    ChunkSerializingError(String),
}

View on GitHub (pinned to 8d4639e25a)