What causes "Unsupported platform: ${process.platform}" in microsoft/playwright?

Set PLAYWRIGHT_BROWSERS_PATH to an explicit directory so computeDefaultCacheDirectory is bypassed.

microsoft/playwright · error · Error

Unsupported platform: ${process.platform}

Error message

Unsupported platform: ${process.platform}

What it means

computeDefaultCacheDirectory() selects the browser-binary cache root based on process.platform: XDG_CACHE_HOME or ~/.cache on linux, ~/Library/Caches on darwin, LOCALAPPDATA or ~/AppData/Local on win32. Any other platform value throws. This runs when PLAYWRIGHT_BROWSERS_PATH is unset and no override configured.

Source

Thrown at packages/playwright-core/src/serverRegistry.ts:252

    });
  }
  return await new Promise(resolve => {
    const socket = net.createConnection(descriptor.endpoint ?? (descriptor as any).pipeName, () => {
      socket.destroy();
      resolve(true);
    });
    socket.on('error', () => resolve(false));
  });
}

function computeDefaultCacheDirectory(): string {
  if (process.platform === 'linux')
    return process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
  if (process.platform === 'darwin')
    return path.join(os.homedir(), 'Library', 'Caches');
  if (process.platform === 'win32')
    return process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
  throw new Error('Unsupported platform: ' + process.platform);
}

let _defaultCacheDirectory: string | undefined;

function defaultCacheDirectory(): string {
  return _defaultCacheDirectory ??= computeDefaultCacheDirectory();
}

function registryDirectory(): string {
  return path.join(defaultCacheDirectory(), 'ms-playwright', 'b');
}

export const serverRegistry = new ServerRegistry();

View on GitHub (pinned to c8fc3bf8d3)

Solutions

Set PLAYWRIGHT_BROWSERS_PATH to an explicit directory so computeDefaultCacheDirectory is bypassed.
Run on a supported platform (linux/darwin/win32).
If on a close-to-Linux platform where the Linux binaries work, set the env var to mirror ~/.cache and ensure binary compatibility.

Example fix

// before (FreeBSD, no env)
// computeDefaultCacheDirectory() throws

// after
// PLAYWRIGHT_BROWSERS_PATH=/home/user/.cache/ms-playwright node server.js

Defensive patterns

Strategy: validation

Validate before calling

function supportedPlatform() { return ['linux','darwin','win32'].includes(process.platform); }
if (!supportedPlatform()) process.env.PLAYWRIGHT_BROWSERS_PATH ||= '/tmp/playwright-cache';

Type guard

function isSupportedPlatform(): boolean { return ['linux','darwin','win32'].includes(process.platform); }

Prevention

Set PLAYWRIGHT_BROWSERS_PATH on uncommon platforms.
Run the registry on linux/darwin/win32.

When it happens

Trigger: Running the Playwright server/registry on an OS whose process.platform is not 'linux', 'darwin', or 'win32' — e.g. a non-Linux POSIX such as FreeBSD, SunOS, or a Node build reporting an unusual platform string.

Common situations: CI on uncommon platforms (FreeBSD, AIX). Custom Node runtimes reporting unexpected platform values. Embedded/edge environments.

Related errors

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