What causes "tilemap dimensions are too large" in kitao/pyxel?

Use Tilemap::try_new and handle the Err instead of panicking.

tilemap dimensions are too large

Error message

tilemap dimensions are too large

What it means

`Tilemap::new` builds an internal Canvas sized width*height tiles; if that canvas cannot be created (checked multiplication overflow / size limit), try_new returns Err and `new` panics with 'tilemap dimensions are too large'.

Source

Thrown at crates/pyxel-core/src/tilemap.rs:46

            ImageSource::Index(index) => crate::pyxel::images()[*index as usize].clone(),
            ImageSource::Image(image) => image.clone(),
        }
    }
}

#[derive(Clone)]
pub struct Tilemap {
    pub imgsrc: ImageSource,
    pub(crate) canvas: Canvas<Tile>,
}

define_rc_type!(RcTilemap, Tilemap);

impl Tilemap {
    // Constructors

    pub fn new(width: u32, height: u32, imgsrc: ImageSource) -> RcTilemap {
        Self::try_new(width, height, imgsrc).expect("tilemap dimensions are too large")
    }

    pub fn try_new(width: u32, height: u32, imgsrc: ImageSource) -> Result<RcTilemap, String> {
        let canvas = Canvas::try_new(width, height)
            .ok_or_else(|| "tilemap dimensions are too large".to_string())?;
        Ok(new_rc_type!(Self { imgsrc, canvas }))
    }

    pub fn from_tmx(filename: &str, layer_index: u32) -> Result<RcTilemap, String> {
        parse_tmx(filename, layer_index)
    }

    // Public accessors

    pub const fn width(&self) -> u32 {
        self.canvas.width()
    }

View on GitHub (pinned to 50f9bd7778)

Solutions

Use Tilemap::try_new and handle the Err instead of panicking.
Validate/clamp tilemap width and height before construction.
Fix the source data (resource file dimensions) if it declares oversized maps.

Example fix

// before
let tm = Tilemap::new(w, h, imgsrc);
// after
let tm = Tilemap::try_new(w, h, imgsrc).map_err(|e| format!("cannot create tilemap: {e}"))?;

Defensive patterns

Strategy: validation

Validate before calling

fn valid_tilemap_dims(w: u32, h: u32) -> bool {
    w.checked_mul(h).is_some()
}

Try / catch

// use the fallible API instead of catching the panic
match Tilemap::try_new(w, h, imgsrc) {
    Ok(tm) => tm,
    Err(msg) => { /* log and use a smaller default tilemap */ }
}

Prevention

Prefer Tilemap::try_new over Tilemap::new for dynamic or untrusted dimensions.
Validate tilemap dimensions in resource files before loading.
Clamp procedurally generated map sizes to a safe maximum.

When it happens

Trigger: Calling Tilemap::new(width, height, imgsrc) with a width*height tile count exceeding the canvas limit, or constructing tilemaps from resources whose declared dimensions are impossible.

Common situations: Corrupted or hand-edited .tmx/resource files with bogus dimensions; generating procedural tilemaps from unbounded user input; misreading the API as expecting pixels rather than tiles (or vice versa) leading to huge numbers.

Related errors

AI-assisted analysis of kitao/pyxel@50f9bd7778 (2026-09-03). Data as JSON: /api/errors/8b0fc222d03e2aec. Report an issue: GitHub.