Debugging WebGL: chrome://gpu, Spector.js & Shader Errors

1. Why WebGL fails silently

Unlike most JavaScript APIs, calling a WebGL function with the wrong state rarely throws a catchable exception. A shader that fails to compile still returns a valid-looking (but unusable) shader object. A texture bound to the wrong unit doesn't error — it just samples black, or garbage, or the wrong image. Because WebGL mirrors OpenGL's C API design, error information sits in an internal error flag you have to poll (gl.getError()), not an exception you can catch.

The practical consequence: "nothing rendered" or "it's the wrong colour" can have a dozen different root causes with zero stack trace pointing at any of them. The tools below exist specifically to make that invisible state visible again.

2. chrome://gpu — driver & feature status

Navigate to chrome://gpu in Chrome (or about:support in Firefox) for a full diagnostic report before you write a single line of debug code. The "Graphics Feature Status" table is the first thing to check — every row should read Hardware accelerated:

Below the feature table, the "Problems Detected" section lists exactly which driver bugs Chrome has blocklisted for your specific GPU/driver combination — useful for distinguishing "my shader is wrong" from "this driver has a known bug with this exact extension."

3. Finding the real GPU behind ANGLE

gl.getParameter(gl.RENDERER) on Chrome usually returns a generic string like "ANGLE (Google, Vulkan 1.3.0...)" — not useful for telling which physical GPU is actually running your shaders. The WEBGL_debug_renderer_info extension exposes the real values:

const gl = canvas.getContext('webgl2');
const ext = gl.getExtension('WEBGL_debug_renderer_info');

if (ext) {
  console.log('Vendor:', gl.getParameter(ext.UNMASKED_VENDOR_WEBGL));
  console.log('Renderer:', gl.getParameter(ext.UNMASKED_RENDERER_WEBGL));
} else {
  // Extension unavailable — often blocked by a privacy setting or older browser
  console.log('Masked renderer:', gl.getParameter(gl.RENDERER));
}

4. Frame-by-frame capture with Spector.js

Spector.js (browser extension or npm package) records every single WebGL call made during one frame and lets you step through them: bound textures, active shader, uniform values, vertex attribute layout, and the actual framebuffer contents after each draw call.

// npm install --save-dev spectorjs
import { Spector } from 'spectorjs';

const spector = new Spector();
spector.displayUI(); // adds the floating capture button
// or trigger a capture programmatically:
spector.captureCanvas(canvas);

A typical debugging session: capture one frame, then scan the call list for the draw call that should be rendering your missing object. Spector.js shows the exact GL state at that call — if the bound texture thumbnail is blank, you know it's a texture upload bug; if the vertex count is 0, it's a bufferData/attribute setup bug; if the shader shows a compile error icon, jump straight to section 5.

5. Checking shader compile/link errors correctly

This is the single highest-value fix most WebGL codebases are missing: gl.compileShader() and gl.linkProgram() never throw and never log anything by default. A broken shader silently produces an unusable object unless you explicitly check for it:

function compileShader(gl, type, source) {
  const shader = gl.createShader(type);
  gl.shaderSource(shader, source);
  gl.compileShader(shader);

  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    const log = gl.getShaderInfoLog(shader);
    gl.deleteShader(shader);
    throw new Error(`Shader compile failed:\n${log}`);
  }
  return shader;
}

function linkProgram(gl, vertexShader, fragmentShader) {
  const program = gl.createProgram();
  gl.attachShader(program, vertexShader);
  gl.attachShader(program, fragmentShader);
  gl.linkProgram(program);

  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
    const log = gl.getProgramInfoLog(program);
    gl.deleteProgram(program);
    throw new Error(`Program link failed:\n${log}`);
  }
  return program;
}

Link errors are a distinct, easy-to-miss failure mode: compilation can succeed for both shaders individually while linking still fails — most commonly a varying mismatch (a fragment shader in variable with no matching vertex shader out of the same name and type), or exceeding the platform's maximum varying/uniform vector count.

6. Handling WebGL context loss

The GPU driver can reclaim a WebGL context at any time — a laptop switching GPUs, another tab exhausting VRAM, the OS recovering from a driver crash. Without a listener, this leaves a permanently black canvas with no error at all:

canvas.addEventListener('webglcontextlost', (e) => {
  e.preventDefault(); // required — tells the browser you intend to restore it
  cancelAnimationFrame(rafId);
  console.warn('WebGL context lost — pausing render loop');
});

canvas.addEventListener('webglcontextrestored', () => {
  console.warn('WebGL context restored — reinitialising GL resources');
  initGLResources(); // buffers, textures, and programs must all be recreated
  requestAnimationFrame(renderLoop);
});

You can force context loss for testing via the WEBGL_lose_context extension: gl.getExtension('WEBGL_lose_context').loseContext() — essential for verifying your recovery path actually works before it happens to a real user.

7. Checklist: the usual suspects