microsoft/playwright · error · Error

webkit-wsl is only supported on Windows

Error message

webkit-wsl is only supported on Windows

What it means

Thrown by the webkit-wsl executable's executablePathOrDie when wslExecutable is undefined, which happens whenever process.platform is not win32. The webkit-via-WSL build only has a launcher path (System32\wsl.exe) on Windows, so requesting its executable on macOS/Linux is unsupported.

Source

Thrown at packages/playwright-core/src/server/registry/index.ts:738

      installType: webkit.installByDefault ? 'download-by-default' : 'download-on-demand',
      _validateHostRequirements: (sdkLanguage: string) => this._validateHostRequirements(sdkLanguage, webkit.dir, webkitLinuxLddDirectories, ['libGLESv2.so.2', 'libx264.so'], ['']),
      downloadURLs: this._downloadURLs(webkit),
      title: webkit.title,
      revision: webkit.revision,
      browserVersion: webkit.browserVersion,
      _install: force => this._downloadExecutable(webkit, force, webkitExecutable),
      _dependencyGroup: 'webkit',
      _isHermeticInstallation: true,
    });
    const wslExecutable = process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'wsl.exe') : undefined;
    this._executables.push({
      name: 'webkit-wsl',
      browserName: 'webkit',
      directory: webkit.dir,
      executablePath: () => wslExecutable,
      executablePathOrDie: () => {
        if (!wslExecutable)
          throw new Error(`webkit-wsl is only supported on Windows`);
        return wslExecutable;
      },
      // WebKit is installed inside the WSL distribution by install_webkit_wsl.ps1.
      wslExecutablePath: `/home/pwuser/.cache/ms-playwright/webkit-${webkit.revision}/pw_run.sh`,
      installType: 'download-on-demand',
      title: 'Webkit in WSL',
      _validateHostRequirements: (sdkLanguage: string) => Promise.resolve(),
      _isHermeticInstallation: true,
      _install: async () => {
        if (process.platform !== 'win32')
          throw new Error(`WebKit via WSL is only supported on Windows`);
        const script = path.join(BIN_PATH, 'install_webkit_wsl.ps1');
        const { code } = await spawnAsync('powershell.exe', [
          '-ExecutionPolicy', 'Bypass',
          '-File', script,
        ], {
          stdio: 'inherit',
        });

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. On macOS/Linux, use the regular webkit build (npx playwright install webkit) instead of webkit-wsl.
2. Gate webkit-wsl usage behind a process.platform === 'win32' check in your config.
3. Exclude webkit-wsl from cross-platform executable enumeration.

Example fix

// before
const exe = registry.findExecutable('webkit-wsl')!.executablePathOrDie(); // throws off-Windows
// after
const name = process.platform === 'win32' ? 'webkit-wsl' : 'webkit';
const exe = registry.findExecutable(name)!.executablePathOrDie();

if (name === 'webkit-wsl' && process.platform !== 'win32')
  throw new Error('webkit-wsl is Windows-only; use webkit on this platform');

function isWindowsOnlyExecutable(name: string): boolean {
  return name === 'webkit-wsl';
}

When it happens

Trigger: Enumerating or launching the webkit-wsl executable on a non-Windows host; a config that selects webkit-wsl unconditionally regardless of OS; tooling that iterates all registered executables including webkit-wsl on macOS/Linux.

Common situations: Cross-platform test matrices that include webkit-wsl by name; scripts copied from a Windows setup to a macOS/Linux developer machine; CI runners on macOS selecting the wrong webkit variant.

Related errors

• WebKit via WSL is only supported on Windows
• Failed to install WebKit via WSL
• Unsupported platform: ${process.platform}
• ${name} is not supported on ${hostPlatform}
• ERROR: Playwright does not support ${descriptor.name} on ${h

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/b133e7bd06943a8c. Report an issue: GitHub.