Skip to content
CC Switch WikiUnofficial Community Wiki

Main window completely blank (pure white) - CC Switch

Quick fix

Set WEBKIT_DISABLE_DMABUF_RENDERER=0 to restore normal rendering under WebKitGTK 2.52 + Mesa.

Symptom

Section titled “Symptom”
Error output
主窗口完全空白(纯白),托盘、代理、数据库等其余功能正常。
English translation

Main window completely blank (pure white); tray, proxy, database, and other functions remain normal.

Cause

Section titled “Cause”

In Linux environments, cc-switch's `src-tauri/src/main.rs` code unconditionally forces `WEBKIT_DISABLE_DMABUF_RENDERER=1` (unless pre-set by the user). This setting was originally intended to avoid DMA-BUF renderer crashes on older NVIDIA GPUs or in the old WebKitGTK era.

However, in modern environments (e.g., WebKitGTK 2.52.3 + Mesa 26 + AMD/Intel GPU), the DMABUF rendering path is actually healthy. When the app forcibly disables DMABUF, WebKit falls back to initializing via the EGL path, but this fallback path fails directly under new driver and library combinations, causing the WebProcess to abort (error: `Could not create default EGL display: EGL_BAD_PARAMETER. Aborting...`). After the WebProcess dies, the WebView cannot load content, resulting in a pure white blank main interface. Note that the 'Disable hardware acceleration' option within the app only affects web content rendering strategies and cannot prevent the underlying EGL initialization crash of WebKit.

Fix

Section titled “Fix”

  1. Before launching cc-switch, set the environment variable `WEBKIT_DISABLE_DMABUF_RENDERER` to `0`. This allows the app to respect external presets instead of forcibly overriding it to `1`, thereby enabling WebKit to use the normal DMABUF rendering path.

Affected Versions

Section titled “Affected Versions”
ToolClaude Code
Version3.19.0 - 3.19.2
PlatformsLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 2 real issues

FAQ

Section titled “FAQ”
Why does setting WEBKIT_DISABLE_DMABUF_RENDERER=1 cause the main window to turn white?
Because this setting disables the healthy rendering path for WebKitGTK 2.52+ on modern Linux distributions (such as Ubuntu 26.04). Upon disabling, WebKit attempts to initialize using the EGL fallback path but encounters a fatal error (abort), causing the rendering process to exit and leaving the interface blank.
I disabled hardware acceleration in the app settings, why doesn't it work?
The 'Disable hardware acceleration' configuration in the app only applies to web content rendering strategies; it cannot prevent the underlying WebKit engine from checking EGL/DMABUF renderers during startup initialization. You must fix the underlying initialization crash by setting the environment variable `WEBKIT_DISABLE_DMABUF_RENDERER=0`.
Does this problem only occur on AMD graphics cards?
Although Issue #6514 reports an AMD (amdgpu) environment, the root cause lies in how newer WebKitGTK handles the EGL fallback path with Mesa. Any Linux user running WebKitGTK 2.52+ with a relatively new Mesa version (including Intel or specific NVIDIA configurations) encountering this blank page issue can resolve it using this method.
Section titled “Related problems”
There's an issue with the selected modelEnable local proxy and rectifier, and correctly set ANTHROPIC_BASE_URL to resolve NVIDIA or MiniMax model call failures.1 issues mergedBash(...) Waiting... Claude CodeDowngrade Claude Code to v2.1.104 or v2.0.64 (admin required), or switch to a compatible provider such as Alibaba Cloud Bailian.1 issues mergedKMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission deniedResolve cc-switch white screen DRM permission errors on Linux by disabling WebKit hardware acceleration, specifying NVIDIA rendering, or using the CLI version.2 issues merged

This is an unofficial community wiki with no affiliation to the cc-switch authors or the project itself. Its content is compiled from the project's public GitHub issues. This site distributes no software.