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

NativeOptions.multisampling is a usize, but glutin's ConfigTemplateBuilder::with_multisampling takes a u8. The try_into().expect() panics during run_native setup when the configured sample count exceeds 255 (u8::MAX). MSAA sample counts are only meaningful as small powers of two (2/4/8), so any value over 255 is a configuration mistake.

Source

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

        /*  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::create_winit_window_attributes(
                egui_ctx,
                viewport_builder.clone(),
            )));

View on GitHub (pinned to d802a982ce)

Solutions

1. Set multisampling to a valid MSAA sample count: 0 (disabled), 2, 4, or 8.
2. Clamp user-supplied config before calling run_native: options.multisampling = options.multisampling.min(8).
3. Validate options early in main() with a clear error message instead of letting eframe panic.

Example fix

// before
let options = eframe::NativeOptions { multisampling: 1024, ..Default::default() };
// after
let options = eframe::NativeOptions { multisampling: 8, ..Default::default() };

fn validate_options(options: &eframe::NativeOptions) -> Result<(), String> {
    let ms = options.multisampling;
    if ms > u8::MAX as usize {
        return Err(format!("multisampling must be 0-255, got {ms}"));
    }
    if ms != 0 && !ms.is_power_of_two() {
        return Err(format!("multisampling must be 0 or a power of two, got {ms}"));
    }
    Ok(())
}

When it happens

Trigger: run_native with NativeOptions { multisampling: 256 or higher, .. } — e.g. 512 or 1024 — on any platform using the Glow renderer.

Common situations: Copying a 'quality level' number from another API, computing multisampling from a formula that can grow unbounded, or mistaking the field for a general quality knob.

Related errors

• Single-use AppCreator has unexpectedly already been taken
• failed to construct C string from string for gl proc address

AI-assisted analysis of emilk/egui@d802a982ce (2026-08-16). Data as JSON: /api/errors/ffb9b6e53ddb4969. Report an issue: GitHub.