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

Use Image::try_new and handle the Err(String) instead of panicking via new().

image dimensions are too large

Error message

image dimensions are too large

What it means

`Image::new` delegates to `Canvas::try_new` and panics when the pixel buffer cannot be created because width*height overflows or is otherwise too large. The error string 'image dimensions are too large' surfaces this guard to the image API.

Source

Thrown at crates/pyxel-core/src/image.rs:50

pub struct Image {
    pub(crate) canvas: Canvas<Color>,
    pub(crate) palette: [Color; MAX_COLORS as usize],
    pub(crate) palette_is_identity: bool,
}

impl ToIndex for Color {
    fn to_index(&self) -> usize {
        *self as usize
    }
}

define_rc_type!(RcImage, Image);

impl Image {
    // Constructors

    pub fn new(width: u32, height: u32) -> RcImage {
        Self::try_new(width, height).expect("image dimensions are too large")
    }

    pub fn try_new(width: u32, height: u32) -> Result<RcImage, String> {
        let canvas = Canvas::try_new(width, height)
            .ok_or_else(|| "image dimensions are too large".to_string())?;
        Ok(new_rc_type!(Self {
            canvas,
            palette: array::from_fn(|i| i as Color),
            palette_is_identity: true,
        }))
    }

    pub fn from_image(filename: &str, include_colors: Option<bool>) -> Result<RcImage, String> {
        let include_colors = include_colors.unwrap_or(false);
        let file_image = image::open(Path::new(&filename))
            .map_err(|_| format!("Failed to open file '{filename}'"))?
            .to_rgb8();

View on GitHub (pinned to 50f9bd7778)

Solutions

Use Image::try_new and handle the Err(String) instead of panicking via new().
Clamp/validate width and height before construction.
Verify the source resource file is not corrupted or oversized.

Example fix

// before
let img = Image::new(w, h);
// after
let img = Image::try_new(w, h).map_err(|e| format!("cannot create image: {e}"))?;

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

// use the fallible API instead of catching the panic
match Image::try_new(w, h) {
    Ok(img) => img,
    Err(msg) => { /* log/limit size, fallback */ Image::new(default_w, default_h) }
}

Prevention

Prefer Image::try_new over Image::new for runtime-derived sizes.
Validate resource file headers before constructing images.
Keep dimension limits consistent with Pyxel's canvas maximums in config.

When it happens

Trigger: Calling Image::new(w, h) (or constructors that build an Image internally, e.g. Pyxel's screen/image resources) with dimensions whose product exceeds the canvas limit, causing try_new to return Err.

Common situations: Loading resource files with corrupted/oversized image headers; passing user-controlled sizes into image creation; porting assets sized for other tools that exceed Pyxel's canvas limits.

Related errors

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