emilk/egui · error

{err}

Error message

{err}

What it means

image_snapshot_options is the panicking wrapper around try_image_snapshot_options: it performs the snapshot comparison and panics with the error message if the snapshot fails (mismatch, missing reference, write error, etc.). It exists so tests can simply call it and abort on any snapshot failure. Use try_image_snapshot_options for non-panicking handling.

Source

Thrown at crates/egui_kittest/src/snapshot.rs:665

///
/// The snapshot files will be saved under [`SnapshotOptions::output_path`].
/// The snapshot will be saved under `{output_path}/{name}.png`.
/// The new image from the most recent test run will be saved under `{output_path}/{name}.new.png`.
/// If the new image didn't match the snapshot, a diff image will be saved under `{output_path}/{name}.diff.png`.
///
/// # Panics
/// Panics if the image does not match the snapshot or if there was an error reading or writing the
/// snapshot.
#[track_caller]
pub fn image_snapshot_options(
    current: &image::RgbaImage,
    name: impl Into<String>,
    options: &SnapshotOptions,
) {
    match try_image_snapshot_options(current, name, options) {
        Ok(()) => {}
        Err(err) => {
            panic!("{err}");
        }
    }
}

/// Image snapshot test.
///
/// The snapshot will be saved under `tests/snapshots/{name}.png`.
/// The new image from the last test run will be saved under `tests/snapshots/{name}.new.png`.
/// If the new image didn't match the snapshot, a diff image will be saved under `tests/snapshots/{name}.diff.png`.
///
/// # Panics
/// Panics if the image does not match the snapshot or if there was an error reading or writing the
/// snapshot.
#[track_caller]
pub fn image_snapshot(current: &image::RgbaImage, name: impl Into<String>) {
    match try_image_snapshot(current, name) {
        Ok(()) => {}
        Err(err) => {

View on GitHub (pinned to 441971a776)

Solutions

1. Inspect the diff image written next to the snapshot to see what changed
2. Re-run with UPDATE_SNAPSHOTS=1 to accept intentional visual changes, then commit the updated snapshots
3. Check for DPI/scale/platform differences between capture and test environments
4. Use try_image_snapshot_options if you need custom failure handling instead of a panic

Example fix

// before
image_snapshot_options(&image, "my_snapshot", &options);
// after
if let Err(err) = try_image_snapshot_options(&image, "my_snapshot", &options) {
    eprintln!("snapshot failed: {err}");
}

// ensure the reference snapshot exists before a Test-mode comparison
let snapshot_path = std::path::Path::new("snapshots/my_snapshot.png");
assert!(snapshot_path.exists(), "reference snapshot missing; run with UPDATE_SNAPSHOTS=1 first");

match try_image_snapshot_options(&image, "my_snapshot", &options) {
    Ok(()) => {}
    Err(err) => eprintln!("snapshot mismatch: {err}"),
}

When it happens

Trigger: Calling image_snapshot_options (or harness.snapshot()) when the current image differs from the stored snapshot beyond the diff threshold, the reference snapshot file does not yet exist in Test mode, or writing/reading snapshot files fails.

Common situations: A UI change (new font, scaling, theme) altering rendered output; running tests on a platform/DPI with different rendering than snapshots were captured on; forgetting to commit new reference snapshots created in update mode.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• {err}
• Unsupported value for UPDATE_SNAPSHOTS: {unknown:?}
• Harness::ui_id is only available for harnesses built with a
• {}
• Multiple SnapshotResults were dropped without being handled

AI-assisted analysis of emilk/egui@441971a776 (2026-09-12). Data as JSON: /api/errors/f16d944417922438. Report an issue: GitHub.