WebGPU Troubleshooting Guide

Fresh 🌱

Source: WebGPU Troubleshooting TipsLast Updated: October 17, 2025

Problem 1: navigator.gpu is undefined

Error:

Uncaught TypeError: Cannot read properties of undefined (reading 'requestAdapter')

Causes and Fixes (check in order):

Check	Fix
Chrome < 113 (desktop) or < 121 (Android)	Update: chrome://settings/help
HTTP context (not localhost)	Use https:// or npx http-server on localhost
Platform not supported yet	Enable chrome://flags/#enable-unsafe-webgpu

Quick Local Dev Fix

# Serve locally over HTTP (localhost is always secure)
npx http-server
# or
python3 -m http.server

Problem 2: GPU Adapter is null

Error:

Uncaught TypeError: Cannot read properties of undefined (reading 'requestDevice')

Causes adapter to be null (check in order):

#	Cause	Fix
1	Hardware acceleration disabled	chrome://settings/system → enable "Use graphics acceleration"
2	Platform not supported	Enable chrome://flags/#enable-unsafe-webgpu; Linux also needs #enable-vulkan
3	GPU hardware blocklisted	Enable chrome://flags/#enable-unsafe-webgpu + #ignore-gpu-blocklist
4	Wrong requestAdapter() options	Try without powerPreference, or different value
5	No GPU detected	Check chrome://gpu — must show a GPU
6	GPU process crashed repeatedly	Reload page; restart Chrome

Diagnostic:

// Check if WebGPU exists
if (!navigator.gpu) {
  console.error('No navigator.gpu — browser too old or unsecure context');
} else {
  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    console.error('null adapter — check chrome://gpu and chrome://settings/system');
  }
}

Problem 3: WebGPU is Slower than WebGL

Diagnosis steps:

1. Check hardware acceleration:

   • Visit chrome://gpu
   • Look for "WebGPU: Hardware accelerated"
   • If "Software only, hardware acceleration unavailable" → update GPU drivers

2. Check if you're porting naively:

   • Direct WebGL-to-WebGPU translations miss WebGPU-specific optimizations
   • Move heavy work to compute shaders
   • Use storage buffers instead of passing data through textures
   • Use asynchronous patterns — avoid sync readbacks

3. Verify pipeline is correct:

// Bad: creating pipelines every frame
function renderFrame() {
  const pipeline = device.createRenderPipeline(...); // DON'T DO THIS
}

// Good: create once, reuse every frame
const pipeline = device.createRenderPipeline(...);
function renderFrame() {
  // reuse pipeline
}

Problem 4: Windows GPU Adapter Issues

• Chrome does not support multiple GPU adapters simultaneously (issue 329211593)
• powerPreference: 'high-performance' has no effect on Windows — Chrome always uses the adapter allocated for other workloads (usually integrated GPU on laptops)
• Force discrete GPU: chrome://flags/#force-high-performance-gpu

Problem 5: Device Lost

device.lost.then((info) => {
  console.error(`Device lost: ${info.message} (reason: ${info.reason})`);
  // Possible reasons: 'destroyed', 'unknown'
  if (info.reason !== 'destroyed') {
    // Re-initialize WebGPU
    initWebGPU();
  }
});

Common causes: GPU driver crash, device timeout, calling device.destroy()

Quick Diagnosis Checklist

[ ] chrome://gpu shows "WebGPU: Hardware accelerated"
[ ] Chrome version: desktop 113+ / Android 121+
[ ] Context is HTTPS or localhost
[ ] "Use graphics acceleration" enabled in chrome://settings/system
[ ] GPU not on blocklist (or #ignore-gpu-blocklist enabled)
[ ] device.lost handler registered
[ ] pipeline created ONCE (not every frame)
[ ] No sync readbacks in render loop

See Also

• Initialize WebGPU SOP
• Chrome Flags Reference