wgpu-core resolves `Auto` before configuring the surface

Error message

wgpu-core resolves `Auto` before configuring the surface

What it means

`map_surface_color_space` in the Vulkan backend converts a wgpu `SurfaceColorSpace` to a `vk::ColorSpaceKHR`. The `Auto` variant is a wgpu-level placeholder that must be resolved to a concrete color space by wgpu-core (based on surface capabilities) before any backend configuration happens, so reaching the Vulkan mapper with `Auto` is an internal invariant violation and panics via unreachable!.

Source

Thrown at wgpu-hal/src/vulkan/conv.rs:199

}

pub fn map_vk_color_space(color_space: vk::ColorSpaceKHR) -> Option<wgt::SurfaceColorSpace> {
    use wgt::SurfaceColorSpace as Scs;
    Some(match color_space {
        vk::ColorSpaceKHR::SRGB_NONLINEAR => Scs::Srgb,
        vk::ColorSpaceKHR::EXTENDED_SRGB_LINEAR_EXT => Scs::ExtendedSrgbLinear,
        vk::ColorSpaceKHR::EXTENDED_SRGB_NONLINEAR_EXT => Scs::ExtendedSrgb,
        vk::ColorSpaceKHR::DISPLAY_P3_NONLINEAR_EXT => Scs::DisplayP3,
        vk::ColorSpaceKHR::HDR10_ST2084_EXT => Scs::Bt2100Pq,
        vk::ColorSpaceKHR::HDR10_HLG_EXT => Scs::Bt2100Hlg,
        _ => return None,
    })
}

pub fn map_surface_color_space(color_space: wgt::SurfaceColorSpace) -> vk::ColorSpaceKHR {
    use wgt::SurfaceColorSpace as Scs;
    match color_space {
        Scs::Auto => unreachable!("wgpu-core resolves `Auto` before configuring the surface"),
        Scs::Srgb => vk::ColorSpaceKHR::SRGB_NONLINEAR,
        Scs::ExtendedSrgbLinear => vk::ColorSpaceKHR::EXTENDED_SRGB_LINEAR_EXT,
        Scs::ExtendedSrgb => vk::ColorSpaceKHR::EXTENDED_SRGB_NONLINEAR_EXT,
        Scs::DisplayP3 => vk::ColorSpaceKHR::DISPLAY_P3_NONLINEAR_EXT,
        Scs::Bt2100Pq => vk::ColorSpaceKHR::HDR10_ST2084_EXT,
        Scs::Bt2100Hlg => vk::ColorSpaceKHR::HDR10_HLG_EXT,
        Scs::ExtendedDisplayP3 => {
            unreachable!("`ExtendedDisplayP3` is never reported in the Vulkan surface capabilities")
        }
    }
}

impl crate::Attachment<'_, super::TextureView> {
    pub(super) fn make_attachment_key(&self, ops: crate::AttachmentOps) -> super::AttachmentKey {
        super::AttachmentKey {
            format: self.view.raw_format,
            layout: derive_image_layout(self.usage, self.view.format),
            ops,

View on GitHub (pinned to 3e11ff59bf)

Solutions

Use the public `Surface::configure(&device, &SurfaceConfiguration)` API and let wgpu-core resolve Auto for you
If you need a deterministic color space, set `color_space` explicitly to `Srgb` or `ExtendedSrgbLinear` instead of `Auto`
Update wgpu — if this fires through the normal public API, it is a bug; check the changelog and file an issue with a reproducer

Example fix

// before
let mut config = surface.get_default_config(&adapter, size.into()).unwrap();
config.color_space = wgpu::SurfaceColorSpace::Auto; // must be resolved by core
surface.configure(&device, &config);
// after
let mut config = surface.get_default_config(&adapter, size.into()).unwrap();
config.color_space = wgpu::SurfaceColorSpace::ExtendedSrgbLinear;
surface.configure(&device, &config);

Defensive patterns

Strategy: validation

Validate before calling

if config.color_space == wgpu::SurfaceColorSpace::Auto {
    // resolve via surface capabilities before configuring
    config.color_space = wgpu::SurfaceColorSpace::Srgb;
}

Type guard

fn is_resolved_color_space(cs: wgpu::SurfaceColorSpace) -> bool {
    !matches!(cs, wgpu::SurfaceColorSpace::Auto)
}

Try / catch

catch (e) { if (String(e).includes('resolves `Auto`')) { config.color_space = wgpu::SurfaceColorSpace::Srgb; surface.configure(device, config); } }

Prevention

Only set SurfaceConfiguration through the public Surface::configure path
Prefer explicit color spaces over Auto when targeting specific backends
Keep wgpu up to date so Auto resolution bugs are patched

When it happens

Trigger: Calling surface configuration paths with `SurfaceConfiguration { color_space: SurfaceColorSpace::Auto, .. }` in a way that bypasses wgpu-core's Auto-resolution step, or an internal wgpu bug where configure_surface reaches hal with Auto still set.

Common situations: Almost exclusively a wgpu-internal bug or a user constructing a SurfaceConfiguration manually and forwarding it through an internal/core API without going through the public `Surface::configure` resolution path; could also appear in forks or bindings that skip wgpu-core validation.

Related errors

AI-assisted analysis of gfx-rs/wgpu@3e11ff59bf (2026-09-03). Data as JSON: /api/errors/d79ff4260203a0b1. Report an issue: GitHub.