[Bug]: electron.launch() fails with "Process failed to launch!" when ELECTRON_RUN_AS_NODE is set in the environment

Open
#44,272 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@microsoft-playwright-automation is already working on this.

Since Nov 21, 2026.

  • #44273 by @microsoft-playwright-automation — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
20/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
electron, node.js, playwright, testing-qa, typescript
Domain
desktop, testing

Research direction

Read packages/playwright-core/src/server/electron/electron.ts around environment setup and launch, then check the existing tests under tests/electron. The issue identifies removing ELECTRON_RUN_AS_NODE beside NODE_OPTIONS as the proposed change and describes a regression test that launches with that variable set. Done means the launch succeeds in that case; an open linked pull request #44273 already addresses the issue.

Written by the indexing model from the issue text.

Description

agent-triage-done
Version

1.65.1 (latest on npm at the time of writing; the affected source is identical on main at 36b06485cc, file blob a13e4f42f2 on both main and v1.65.1)

Steps to reproduce

Self-contained, two dependencies (@playwright/[email protected] and [email protected], both stock), no Playwright browsers needed. The app opens one window with a heading. The test launches it with _electron.launch() and expects the heading. The only difference between a passing and a failing run is ELECTRON_RUN_AS_NODE=1 in the environment of the Playwright process.

mkdir repro && cd repro
# create the 4 files below
npm install
npx playwright test electron.spec.ts                       # passes
# PowerShell:
$env:ELECTRON_RUN_AS_NODE = '1'; npx playwright test electron.spec.ts   # fails
# bash:
ELECTRON_RUN_AS_NODE=1 npx playwright test electron.spec.ts             # fails

package.json

{
  "name": "pw-electron-run-as-node-repro",
  "private": true,
  "devDependencies": { "@playwright/test": "1.65.1", "electron": "45.4.1" }
}

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({ testDir: '.', timeout: 30000, reporter: 'list' });

main.js

const { app, BrowserWindow } = require('electron');

app.whenReady().then(() => {
  const win = new BrowserWindow({ show: false });
  win.loadURL('data:text/html,<h1>ok</h1>');
});

electron.spec.ts

import { test, expect, _electron as electron } from '@playwright/test';

test('launches an Electron app', async () => {
  const app = await electron.launch({ args: ['main.js'] });
  try {
    const window = await app.firstWindow();
    await expect(window.getByRole('heading', { name: 'ok' })).toBeVisible();
  } finally {
    await app.close();
  }
});
Expected behavior

The app launches and the test passes, as it does without the variable. ELECTRON_RUN_AS_NODE turns the Electron binary into a plain Node.js runtime. It cannot be wanted when launching an Electron app for automation, because Playwright needs the Chromium DevTools endpoint of a real Electron process. Playwright already removes NODE_OPTIONS from the child environment for a similar reason; ELECTRON_RUN_AS_NODE should be handled the same way.

Actual behavior

Without the variable (run a):

Running 1 test using 1 worker

  ✓  1 electron.spec.ts:3:1 › launches an Electron app (5.1s)

  1 passed (5.4s)

With ELECTRON_RUN_AS_NODE=1 (run b), exit code 1:

Running 1 test using 1 worker

  ✘  1 electron.spec.ts:3:1 › launches an Electron app (289ms)

  1) electron.spec.ts:3:1 › launches an Electron app ───────────────────────────────────────────────

    Error: Process failed to launch!

The error does not say why. With DEBUG=pw:browser the cause shows up, the Electron binary running as Node rejects Playwright's own argument:

pw:browser <launching> ".../node_modules/electron/dist/electron.exe" "-r" ".../node_modules/playwright-core/lib/server/electron/loader.js" "--inspect=0" "--remote-debugging-port=0" "main.js"
pw:browser <launched> pid=50016
pw:browser [pid=50016][err] .../node_modules/electron/dist/electron.exe: bad option: --remote-debugging-port=0
pw:browser [pid=50016] <process did exit: exitCode=9, signal=null>

With the variable still set in the shell but removed from the launch environment (run c, the user-side workaround), the test passes:

const app = await electron.launch({ args: ['main.js'], env: { ...process.env, ELECTRON_RUN_AS_NODE: undefined } });
  ✓  1 electron-workaround.spec.ts:4:1 › launches an Electron app (workaround: env without ELECTRON_RUN_AS_NODE) (351ms)

  1 passed (747ms)

(undefined values are skipped by envObjectToArray in packages/playwright-core/src/client/clientHelper.ts, so the variable is not passed on.)

Additional context

Root cause. Source references are to main (36b06485cc); electron.ts is identical at the v1.65.1 tag.

  1. packages/playwright-core/src/server/electron/electron.ts, line 199: const env = options.env ? envArrayToObject(options.env) : process.env;. Without options.env, the child gets the full environment of the Playwright process. With options.env, the child gets exactly that object (it is not merged with process.env).
  2. Line 237: delete env.NODE_OPTIONS; is the only variable that is removed (with the comment about the debugger attaching to Electron's Node). Nothing in playwright-core mentions ELECTRON_RUN_AS_NODE.
  3. Lines 238 to 241 pass env to launchProcess. Electron started with ELECTRON_RUN_AS_NODE=1 behaves as node, so --remote-debugging-port=0 is a bad option and the process exits with code 9.
  4. Lines 270 to 272 wait for Debugger listening on ws://... and DevTools listening on ws://... on stderr; waitForLine (line 325) rejects with Process failed to launch! when stderr closes. The real stderr line (bad option: ...) is only visible with DEBUG=pw:browser.

Why it happens in practice. The variable is set by programs that are themselves Electron apps and spawn child processes. VS Code-based editors set it for processes they start, including MCP servers that run playwright run-test-mcp-server. It surfaced for me when an MCP server was started by Kiro IDE: the Playwright process inherited ELECTRON_RUN_AS_NODE=1, and every electron.launch() from the planner and generator tools failed with the error above.

Related issue. The closed issue #39922 has a comment by @shay-dr (https://github.com/microsoft/playwright/issues/39922#issuecomment-4155709149) that names the same variable: "at least one of my launch environments was inheriting ELECTRON_RUN_AS_NODE=1. That turns out to be an important confounder here." They saw bad option: --remote-debugging-port=0 with Playwright 1.58.2 and Electron 40.2.1, and electron.launch() worked after they removed the variable from the launch environment. That issue was closed, so the variable was never addressed in Playwright. #39008 and #32027 (both closed) show the same bad option: --remote-debugging-port=0 message; I did not check whether the variable was set there.

Proposed fix. Remove the variable next to NODE_OPTIONS:

--- a/packages/playwright-core/src/server/electron/electron.ts
+++ b/packages/playwright-core/src/server/electron/electron.ts
@@ -234,5 +234,8 @@
     // When debugging Playwright test that runs Electron, NODE_OPTIONS
     // will make the debugger attach to Electron's Node. But Playwright
     // also needs to attach to drive the automation. Disable external debugging.
     delete env.NODE_OPTIONS;
+    // ELECTRON_RUN_AS_NODE makes Electron start as plain Node.js, which rejects
+    // --remote-debugging-port and never serves the Chromium DevTools endpoint.
+    delete env.ELECTRON_RUN_AS_NODE;
     const { launchedProcess, gracefullyClose, kill } = await progress.race(launchProcess({

Choice about an explicit options.env: the variable is deleted in both cases, as NODE_OPTIONS already is, because env at that point is the merged result of either source. Keeping it when the user passes it explicitly would not help the common case, where the user spreads process.env (env: { ...process.env, FOO: '1' }) and the variable comes along unnoticed. A launch with ELECTRON_RUN_AS_NODE=1 cannot work with the arguments and the loader that Playwright adds, so there is no working configuration that this would break. If maintainers prefer to keep explicit values, the alternative is to delete it only when options.env is not set, or to fail with a clear message instead of Process failed to launch!.

One side effect to be aware of: when options.env is not set, env is process.env of the Playwright process itself, so the delete mutates it (this already happens for NODE_OPTIONS). Copying first (const env = { ...process.env }) would avoid that, but I left it out to keep the diff minimal.

Tested. I applied the equivalent one-line change to the built file in the repro (node_modules/playwright-core/lib/coreBundle.js, directly after delete env.NODE_OPTIONS;), ran run (b) again with ELECTRON_RUN_AS_NODE=1 in the environment, and then restored the file (hash identical to before):

  ✓  1 electron.spec.ts:3:1 › launches an Electron app (353ms)

  1 passed (678ms)

I did not run Playwright's own test suite with the change and did not add a test to the repository. A regression test for tests/electron would launch the app with ELECTRON_RUN_AS_NODE: '1' in options.env and expect the launch to succeed. I can open a PR if that is welcome.

Notes on the repro.

  • I ran it on Windows only. The code path is not platform specific, and the Electron variable behaves the same on all platforms, but I have not run the repro on Linux or macOS.
  • The first run of (a) prints Downloading Electron binary..., because the Electron binary was fetched on first use; it is unrelated to the report.
  • Run c uses a second spec file with the workaround, so it needs one more file:

electron-workaround.spec.ts

import { test, expect, _electron as electron } from '@playwright/test';

test('launches an Electron app (workaround: env without ELECTRON_RUN_AS_NODE)', async () => {
  const app = await electron.launch({ args: ['main.js'], env: { ...process.env, ELECTRON_RUN_AS_NODE: undefined } });
  try {
    const window = await app.firstWindow();
    await expect(window.getByRole('heading', { name: 'ok' })).toBeVisible();
  } finally {
    await app.close();
  }
});
Environment
System:
  OS: Windows 11 10.0.26100
Binaries:
  Node: 22.22.2
  npm: 10.9.7
npmPackages:
  @playwright/test: 1.65.1 => 1.65.1
  electron: 45.4.1 => 45.4.1
Dominant language
TypeScript
Stars
100k
Forks
6.9k
Avg merge
16h 8m
Merged PRs (30d)
281

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/playwright

All issues in microsoft/playwright

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.