emilk/egui · error

failed to fit multisamples option of native_options into u8

Error message

failed to fit multisamples option of native_options into u8

What it means

In `GlowIntegration::new`, when `NativeOptions::multisampling` is greater than 0, eframe passes it to glutin's `with_multisampling`, which accepts only a `u8`. The `try_into().expect(...)` panics if the configured multisample count exceeds `u8::MAX` (255). The library converts user-supplied config into a glutin-friendly type and fails loudly on overflow.

Solutions

1. Set `multisampling` to a realistic value within 0..=255 (typically 0, 2, 4, 8, or 16).
2. Clamp or validate the value before constructing `NativeOptions`, e.g. `multisampling: requested.min(16) as u8` if you accept user input.
3. If ultra-high sampling was intended, use a different AA approach (e.g. supersample via higher-resolution rendering) instead of MSAA sample count.

Example fix

// before
let options = eframe::NativeOptions {
    multisampling: 512, // panics: doesn't fit u8
    ..Default::default()
};
// after
let requested: i32 = 512;
let options = eframe::NativeOptions {
    multisampling: requested.clamp(0, 16) as u8,
    ..Default::default()
};

// validate before constructing NativeOptions
let requested: i32 = read_multisampling_from_config();
assert!((0..=16).contains(&requested), "multisampling must be 0..=16, got {requested}");
let options = eframe::NativeOptions {
    multisampling: requested as u8,
    ..Default::default()
};

fn valid_multisampling(v: i32) -> Option<u8> {
    u8::try_from(v).ok().filter(|n| *n <= 16)
}

// panics (expect), so no catch is possible; validate the config value first
// e.g. in config parsing:
let multisampling = match raw.parse::<i32>() {
    Ok(v) if (0..=255).contains(&v) => v as u8,
    _ => 4, // safe default
};

When it happens

Trigger: Setting `NativeOptions { multisampling: N, .. }` with N > 255 (or N that cannot fit u8) before calling `eframe::run_native` on the glow backend.

Common situations: Copy-pasting a large sample count (e.g. 1000) or using `u32`/`i32` typed values without narrowing; confusing MSAA sample counts with percentages; typos like 2560 instead of 16.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Failed to get display handle
• Failed to get window handle
• app_mut got the wrong type of App
• Failed to parse
• Failed to read

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

Appendix: source

Thrown at crates/eframe/src/native/glow_integration.rs:1098

        /*  opengl setup flow goes like this:
            1. we create a configuration for opengl "Display" / "Config" creation
            2. choose between special extensions like glx or egl or wgl and use them to create config/display
            3. opengl context configuration
            4. opengl context creation
        */
        // start building config for gl display
        let config_template_builder = glutin::config::ConfigTemplateBuilder::new()
            .prefer_hardware_accelerated(hardware_acceleration)
            .with_depth_size(native_options.depth_buffer)
            .with_stencil_size(native_options.stencil_buffer)
            .with_transparency(native_options.viewport.transparent.unwrap_or(false));
        // we don't know if multi sampling option is set. so, check if its more than 0.
        let config_template_builder = if native_options.multisampling > 0 {
            config_template_builder.with_multisampling(
                native_options
                    .multisampling
                    .try_into()
                    .expect("failed to fit multisamples option of native_options into u8"),
            )
        } else {
            config_template_builder
        };

        log::debug!("trying to create glutin Display with config: {config_template_builder:?}");

        // Create GL display. This may probably create a window too on most platforms. Definitely on `MS windows`. Never on Android.
        let display_builder = glutin_winit::DisplayBuilder::new()
            // we might want to expose this option to users in the future. maybe using an env var or using native_options.
            //
            // The justification for FallbackEgl over PreferEgl is at https://github.com/emilk/egui/pull/2526#issuecomment-1400229576 .
            .with_preference(glutin_winit::ApiPreference::FallbackEgl)
            .with_window_attributes(Some(egui_winit::apply_monitor_to_window_attributes(
                egui_winit::create_winit_window_attributes(egui_ctx, viewport_builder.clone()),
                &viewport_builder,
                event_loop,
            )));

View on GitHub (pinned to 8fb03c9ae9)