[darwin] pty_posix_spawn leaks the pty master+slave when posix_spawn fails, and one ptmx fd on every successful spawn #950

Activity

1. pull

   added a commit that references this issue on Aug 12, 2026

   fix(pty): patch node-pty's darwin fd leak locally (microsoft/node-pty…

   ...

   2153af4
2. ElBartox commented on Sep 7, 2026

   

   ElBartox

   on Sep 7, 2026

   More actions

   Independent confirmation of Leak 2, plus field data on how bad it gets in a long-running app.

   Environment: node-pty 1.1.0, Electron 43, macOS 26.6.2 (arm64), kern.tty.ptmx_max = 511.

   Isolated measurement

   Spawning 5 shells and closing them, counting /dev/ptmx fds held by the process (lsof -p <pid> | grep -w ptmx):

   	ptmx fds
   baseline	0
   5 live PTYs	10
   after kill()	5
   after kill() + destroy()	5

   Exactly one fd leaked per successful spawn, which matches the low_fds[0] off-by-one you identified. Worth noting for anyone arriving here looking for a workaround: destroy() is not one. It closes the socket wrapping term.fd, but the orphaned descriptor is the other one — opened by the native prologue and never exposed to JS (master/slave are undefined on the spawn() path, and p.fd is already closed by then). There is no API-level way to reclaim it; only exiting the process does.

   Field impact

   A desktop app left running for a few days accumulated 391 leaked ptmx fds in a single process. Together with other processes on the machine that reached 510 of 511.

   The important part is the blast radius: once the global table is exhausted, no process on the machine can allocate a PTY — not just the app that leaked them. The failure also surfaces in a way that points at the wrong thing. The user-visible error is the generic

   Error: posix_spawnp failed.
   

   with the working directory in the message, so it reads as "this folder is broken". It is not: spawning failed identically for /tmp and $HOME. Diagnosing it meant reproducing the exhaustion deliberately (holding 105 /dev/ptmx fds open) to confirm the count, rather than anything about the spawn arguments.

   A cheap probe consumers can use to tell this apart from a real spawn failure — open("/dev/ptmx") fails precisely when the table is full:

   function ptysExhausted() {
     let fd;
     try { fd = fs.openSync('/dev/ptmx', 'r+'); return false; }
     catch { return true; }
     finally { if (fd !== undefined) try { fs.closeSync(fd); } catch {} }
   }

   Happy to test a patch against the same reproduction if that helps.
3. ohadpr commented on Sep 29, 2026

   

   ohadpr (ohadpr)

   on Sep 29, 2026

   Last edited by ohadpr

   More actions

   Both leaks in this report are already fixed on main — and there is a third one in the same per-spawn path that is worth adding to the list. The problem now is purely that none of it has shipped to the stable line.

   Already fixed on main

   • Leak 2 (low_fds off-by-one) and the error-path master/slave leaks — fix: /dev/ptmx leak on macOS #882, merged 2026-01-28 (af053f22). It replaces for (; count > 0; count--) close(low_fds[count]) with for (size_t i = 0; i <= count; i++) close(low_fds[i]), closes slave in the parent unconditionally after posix_spawn, adds goto done cleanup on every error path, and — addressing suggestion 3 above — replaces "posix_spawnp failed." with format_error(), so the thrown message finally carries the errno.
   • A third leak, same lifecycle: SetupExitCallback opens int kq = HANDLE_EINTR(kqueue()) (pty.cc:138 in 1.1.0) and never closes it, so a kqueue is lost on every spawn as well, once the child is reaped. Fixed by fix: close kqueue fd in SetupExitCallback on macOS #931.

   All three are inside #if defined(__APPLE__), so Linux (plain forkpty + waitpid) is unaffected — useful for triage, since the reports all come from macOS.

   Measured: 1.1.0 loses three descriptors per spawn, beta.15 loses none

   8 spawn/exit cycles, each child fully exited and released, counting the process's own fds by kind:

   	1.1.0	1.2.0-beta.15
   /dev/ptmx	+8	0
   pty slave (as (revoked) after teardown)	+8	0
   KQUEUE	+8	0

   Confirming ElBartox's point that destroy() is not a workaround: it is flat at +8 with or without it. Field data from a terminal multiplexer daemon on macOS 26.6.2 (arm64), 1.1.0, after a day of ordinary use: 505 /dev/ptmx handles held against kern.tty.ptmx_max = 511, with only 72 ptys actually in use and 362 descriptors in the kernel's (revoked) state. At that point nothing on the machine could allocate a pty — not the app, not a plain terminal, not a browser.

   Harness, no dependencies beyond node-pty:

   // node --expose-gc leak.mjs <path-to-node-pty/lib/index.js>
   import { spawn } from 'node:child_process';
   const pty = await import(process.argv[2]);
   const census = () => new Promise((res) => {
     const p = spawn('sh', ['-c', `lsof -p ${process.pid} | awk 'NR>1{if($9=="/dev/ptmx")a++;else if($9~/\\/dev\\/ttys/)b++;else if($5=="KQUEUE")c++;else if($5=="(revoked)")d++}END{print a+0,b+0,c+0,d+0}'`]);
     let o = ''; p.stdout.on('data', (d) => { o += d; });
     p.on('close', () => res(o.trim()));
   });
   console.log('ptmx ttys kqueue revoked');
   console.log('baseline', await census());
   for (let i = 0; i < 8; i++) {
     const t = pty.spawn('/bin/sh', ['-c', 'exit 0'], { name: 'xterm-256color', cols: 80, rows: 24, cwd: '/tmp', env: process.env });
     t.onData(() => {});
     await new Promise((r) => t.onExit(r));
     t.destroy?.();
     await new Promise((r) => setTimeout(r, 250));
   }
   global.gc(); await new Promise((r) => setTimeout(r, 800));
   console.log('after 8  ', await census());
   process.exit(0);

   The actual remaining ask

   npm dist-tags still reads latest: 1.1.0, beta: 1.2.0-beta.15. 1.1.0 predates every one of these fixes, so the default install — eight months after #882 merged — still leaks three descriptors per spawn and still reports the exhaustion as a bare posix_spawnp failed. Every report in this thread is against 1.1.0 for that reason.

   Is there anything blocking a stable 1.2.0, or a 1.1.1 with just the fd fixes backported? Happy to help test. If a release is not close, it would be worth saying so in the README, because right now the only way to find out that the fix exists is to read main and diff it against what npm installed.
4. Pedro Duarte (pedrogoiania)

   added a commit that references this issue on Oct 2, 2026

   Agent: node-pty 1.2.0-beta.15, stop leaking PTYs on macOS (0.14.2)

   ...

   c3ae459
5. oskarkri commented on Oct 5, 2026

   

   oskarkri

   on Oct 5, 2026

   More actions

   One edge left in the #882 cleanup on main / 1.2.0-beta.15 (src/unix/pty.cc, pty_posix_spawn): if all three posix_openpt() calls in the low-fd prologue fail — which is exactly the pty-exhausted / EMFILE state this thread is about — the loop exits with count == 3, and

   for (size_t i = 0; i <= count; i++) {
     close(low_fds[i]);
   }

   reads low_fds[3], one past the array, and passes whatever is in that stack slot to close(). Before #882 this was effectively unreachable, because the early return after a failed master posix_openpt() skipped the cleanup; with goto done it is now reached on that path.

   In the beta.15 darwin-arm64 prebuild I could not get it to close a live descriptor (50 spawn attempts at the fd ceiling with every fd 0–255 open, none closed), so it looks latent in that particular build — but it is UB, and the slot is shared with other locals in PtyFork, so another build could behave differently.

   Possible fix: initialize int low_fds[3] = {-1, -1, -1};, break on the first -1 in the prologue, and bound the cleanup, e.g. for (size_t i = 0; i < 3 && i <= count; i++) if (low_fds[i] >= 0) close(low_fds[i]);.