Cannot create swapchain with Auto PresentationMode

Error message

Cannot create swapchain with Auto PresentationMode

What it means

`map_present_mode` in the Vulkan backend converts a wgpu `PresentMode` to `vk::PresentModeKHR`. The `AutoVsync`/`AutoNoVsync` variants are wgpu-level placeholders that must be resolved to a concrete present mode (based on the surface's supported modes) before swapchain creation, so passing them to the Vulkan mapper is an invariant violation and panics.

Source

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

    };
    let store_op = if op.contains(crate::AttachmentOps::STORE) {
        vk::AttachmentStoreOp::STORE
    } else if op.contains(crate::AttachmentOps::STORE_DISCARD) {
        vk::AttachmentStoreOp::DONT_CARE
    } else {
        unreachable!()
    };
    (load_op, store_op)
}

pub fn map_present_mode(mode: wgt::PresentMode) -> vk::PresentModeKHR {
    match mode {
        wgt::PresentMode::Immediate => vk::PresentModeKHR::IMMEDIATE,
        wgt::PresentMode::Mailbox => vk::PresentModeKHR::MAILBOX,
        wgt::PresentMode::Fifo => vk::PresentModeKHR::FIFO,
        wgt::PresentMode::FifoRelaxed => vk::PresentModeKHR::FIFO_RELAXED,
        wgt::PresentMode::AutoNoVsync | wgt::PresentMode::AutoVsync => {
            unreachable!("Cannot create swapchain with Auto PresentationMode")
        }
    }
}

pub fn map_vk_present_mode(mode: vk::PresentModeKHR) -> Option<wgt::PresentMode> {
    // Not exposed in Ash yet.
    const FIFO_LATEST_READY: vk::PresentModeKHR = vk::PresentModeKHR::from_raw(1_000_361_000);

    // See https://registry.khronos.org/vulkan/specs/latest/man/html/VkPresentModeKHR.html
    match mode {
        vk::PresentModeKHR::IMMEDIATE => Some(wgt::PresentMode::Immediate),
        vk::PresentModeKHR::MAILBOX => Some(wgt::PresentMode::Mailbox),
        vk::PresentModeKHR::FIFO => Some(wgt::PresentMode::Fifo),
        vk::PresentModeKHR::FIFO_RELAXED => Some(wgt::PresentMode::FifoRelaxed),

        // Modes that aren't exposed yet.
        vk::PresentModeKHR::SHARED_DEMAND_REFRESH => None,
        vk::PresentModeKHR::SHARED_CONTINUOUS_REFRESH => None,

View on GitHub (pinned to 3e11ff59bf)

Solutions

Use the public `Surface::configure` API, which resolves Auto modes against supported present modes automatically
Set an explicit present mode (`Fifo`, `Mailbox`, `Immediate`, `FifoRelaxed`) that the surface supports (check via `surface.get_capabilities(&adapter)`)
If Auto resolution should have happened through the normal path, update wgpu and file a bug with a reproducer

Example fix

// before
config.present_mode = wgpu::PresentMode::AutoVsync; // leaked unresolved to hal
surface.configure(&device, &config);
// after
let caps = surface.get_capabilities(&adapter);
config.present_mode = caps.present_modes.iter().copied()
    .find(|m| !matches!(m, wgpu::PresentMode::AutoVsync | wgpu::PresentMode::AutoNoVsync))
    .unwrap_or(wgpu::PresentMode::Fifo);
surface.configure(&device, &config);

Defensive patterns

Strategy: validation

Validate before calling

let caps = surface.get_capabilities(&adapter);
let resolved = match config.present_mode {
    m @ (wgpu::PresentMode::AutoVsync | wgpu::PresentMode::AutoNoVsync) => {
        caps.present_modes.iter().copied().find(|p| !matches!(p, wgpu::PresentMode::AutoVsync | wgpu::PresentMode::AutoNoVsync)).unwrap_or(wgpu::PresentMode::Fifo)
    }
    m => m,
};
config.present_mode = resolved;

Type guard

fn is_concrete_present_mode(m: wgpu::PresentMode) -> bool {
    !matches!(m, wgpu::PresentMode::AutoVsync | wgpu::PresentMode::AutoNoVsync)
}

Prevention

Let Surface::configure resolve Auto modes; don't pass configs into internal hal APIs
Verify chosen modes against surface.get_capabilities
Default to Fifo, which is universally supported

When it happens

Trigger: Creating a swapchain/surface configuration with `present_mode: PresentMode::AutoVsync` or `AutoNoVsync` in a code path that bypasses wgpu-core's Auto-resolution (e.g. calling internal hal APIs directly, or a wgpu bug where Auto leaks into configure).

Common situations: Hand-rolling SurfaceConfiguration for internal/core APIs; forks or bindings that skip the resolution step; using Auto modes with an API (like an older wgpu version or direct hal usage) that expects them pre-resolved.

Related errors

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