Wayland GPU sandbox validation must run on Linux.

Error message

Wayland GPU sandbox validation must run on Linux.

What it means

assertWaylandHost refuses to run the Wayland GPU sandbox validation on any non-Linux platform. The whole script exists to validate Electron's GPU sandbox behavior under Linux Wayland (ozone), which is meaningless on macOS/Windows. It is the first guard, ahead of the Wayland-session and runtime checks.

Source

Thrown at config/scripts/verify-linux-wayland-gpu-sandbox.mjs:66

  const mode = modeArg?.slice('--mode='.length) ?? 'verify-fix'
  if (mode !== 'verify-fix' && mode !== 'expect-repro') {
    throw new Error(`Unsupported --mode=${mode}`)
  }
  return { mode }
}

function run(command, args, options = {}) {
  execFileSync(command, args, {
    cwd: rootDir,
    env: process.env,
    stdio: 'inherit',
    ...options
  })
}

function assertWaylandHost() {
  if (process.platform !== 'linux') {
    throw new Error('Wayland GPU sandbox validation must run on Linux.')
  }
  if (
    !process.env.WAYLAND_DISPLAY &&
    process.env.XDG_SESSION_TYPE !== 'wayland' &&
    process.env.ELECTRON_OZONE_PLATFORM_HINT !== 'wayland'
  ) {
    throw new Error('Wayland GPU sandbox validation requires a Wayland session.')
  }
}

function ensureElectronRuntime() {
  run(process.execPath, ['config/scripts/ensure-native-runtime.mjs', '--runtime=electron'])
}

function buildAppIfNeeded() {
  if (process.env.SKIP_BUILD === '1' && existsSync(outMain)) {
    console.log('[wayland-gpu] SKIP_BUILD=1 and out/main/index.js exists; skipping build.')
    return

View on GitHub (pinned to 1136503c6a)

Solutions

Run the script on a Linux host (physical, VM, or container with a Wayland session).
Gate the CI job so this script only runs on Linux runners.

Defensive patterns

Strategy: validation

Validate before calling

if (process.platform !== 'linux') {
  console.error('Wayland GPU sandbox validation is Linux-only; skipping on', process.platform)
  process.exit(0) // or exit(1) if you want it hard-gated
}

Prevention

Restrict the wayland validation CI job to Linux runners.
Document that the script is Linux-only in the runbook.

When it happens

Trigger: process.platform !== 'linux' at line 65. Reproduced by invoking the script on macOS or Windows.

Common situations: Running the script from a developer mac or a Windows machine; a CI matrix leg that runs the wayland validation on a non-Linux OS by mistake.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/cf9a809a78abe535. Report an issue: GitHub.