microsoft/playwright · critical · Error

Failed to launch webkit because executable doesn't exist at

Error message

Failed to launch webkit because executable doesn't exist at ${options.executablePath}

What it means

When launching with channel 'webkit-wsl', Playwright runs the WebKit binary inside a WSL distribution and verifies the WSL-side executable path exists via wslPathExists before launching. If options.executablePath was set but the file is not visible inside WSL, launch aborts here rather than producing a confusing wsl.exe error later.

Source

Thrown at packages/playwright-core/src/server/webkit/webkit.ts:74

  override amendEnvironment(env: NodeJS.ProcessEnv, userDataDir: string, isPersistent: boolean, options: types.LaunchOptions): NodeJS.ProcessEnv {
    return {
      ...env,
      // Cookie jar is only used by the Windows port of WebKit.
      CURL_COOKIE_JAR_PATH: process.platform === 'win32' && options.channel !== 'webkit-wsl' && isPersistent ? path.join(userDataDir, 'cookiejar.db') : undefined,
    };
  }

  override supportsPipeTransport(options: types.LaunchOptions): boolean {
    return options.channel !== 'webkit-wsl';
  }

  override async resolveExecutablePath(options: types.LaunchOptions): Promise<string | undefined> {
    if (options.channel !== 'webkit-wsl')
      return super.resolveExecutablePath(options);
    // executablePath points inside the WSL distribution and is consumed in defaultArgs; the
    // host command is wsl.exe from the registry.
    if (options.executablePath && !await wslPathExists(options.executablePath))
      throw new Error(`Failed to launch webkit because executable doesn't exist at ${options.executablePath}`);
    return undefined;
  }

  override async waitForReadyState(options: types.LaunchOptions, browserLogsCollector: RecentLogsCollector): Promise<{ wsEndpoint?: string }> {
    if (options.channel !== 'webkit-wsl')
      return {};
    const result = new ManualPromise<{ wsEndpoint?: string }>();
    browserLogsCollector.onMessage(message => {
      const match = message.match(/Playwright listening on (ws:\/\/\S+)/);
      if (match)
        result.resolve({ wsEndpoint: match[1] });
    });
    return result;
  }

  override doRewriteStartupLog(logs: string): string {
    if (logs.includes('Failed to open display') || logs.includes('cannot open display'))
      logs = '\n' + wrapInASCIIBox(kNoXServerRunningError, 1);

View on GitHub (pinned to c8fc3bf8d3)

Solutions

  1. Confirm the executable exists inside WSL: `wsl -d <distro> -- ls -l <path>`.
  2. Provide a Linux-style absolute path (/usr/... or /home/...) for executablePath, not a Windows path.
  3. If you want Playwright's bundled webkit-wsl build, omit executablePath so registry.findExecutable('webkit-wsl') resolves it.

Example fix

// before
browser = await chromium.launch({ channel: 'webkit-wsl', executablePath: 'C:\\builds\\webkit.exe' });

// after
browser = await chromium.launch({ channel: 'webkit-wsl', executablePath: '/home/user/webkit/bin/playwright-webkit' });
// or omit executablePath to use the bundled build
Defensive patterns

Strategy: validation

Validate before calling

const { execSync } = require('child_process');
function assertWslExists(dist, linuxPath) {
  try {
    execSync(`wsl.exe -d ${dist} -- test -f ${linuxPath}`, { stdio: 'ignore' });
  } catch {
    throw new Error(`WSL executable not found: ${dist}:${linuxPath}`);
  }
}
// call before launch with channel 'webkit-wsl'

Try / catch

try { browser = await chromium.launch({ channel: 'webkit-wsl', executablePath }); }
catch (e) {
  if (/executable doesn't exist/i.test(String(e.message))) {
    // fall back to bundled build, or surface a clear setup error
    browser = await chromium.launch({ channel: 'webkit-wsl' });
  } else throw e;
}

Prevention

When it happens

Trigger: Launching chromium/webkit with channel 'webkit-wsl' and an executablePath that does not exist inside the WSL distribution; the WSL distro not installed; the path using a Windows-style (C:\...) path instead of a Linux (/home/...) path.

Common situations: Switching from a Windows-native build to the webkit-wsl channel without updating the executable path; WSL distro name mismatch; the build artifact not yet copied into the distro.

Related errors

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