CLI exits 0 with no output when node-pty fails to build (missing C toolchain); breaks desktop SSH launch with empty server.log

[TorbenWetter]

Environment: Ubuntu 26.04 LTS minimal server (Hetzner), Node 24.18.1 via mise, npm 11.x. Reproduced with t3@0.0.31 and t3@0.1.0-alpha.1.

Repro: On a machine without a C toolchain (no build-essential):

$ npx -y t3@0.0.31 --version
$ echo $?
0

Prints nothing, exits 0. Same for --help, connect, serve.

Root cause: node-pty fails its node-gyp build (no gcc/make). npm swallows the failure — the npx cache dir ends up essentially empty, node_modules/.bin/t3 never materializes, and npx still exits 0 having run nothing. A plain npm install t3 in an empty dir shows the real gyp ERR! output.

Knock-on effect: the desktop app's SSH-launch flow fails with SshCommandError: Remote T3 server did not become ready on 127.0.0.1:3773 and a 0-byte ~/.t3/ssh-launch/<key>/server.log — nothing points at the actual cause. Installing build-essential fixes everything instantly.

Suggestions:

• preflight check with a clear "install a C toolchain" message
• surface the npm install stderr in the ssh-launch server.log
• or ship prebuilds for node-pty on common platforms

[martinfrancois]

Reproduced on openSUSE MicroOS 20260802 (immutable, no toolchain), node 24.16.0, npm 11.13.0.

One correction to the report. Here npx -y t3@latest --version exits 1, not 0. It is still
completely silent: zero bytes on stdout and zero bytes on stderr. So the "no diagnostic at all"
part reproduces exactly, and the exit code may be npm-version dependent.

Worth separating the two entry points, because only one of them is silent:

• npm install -g t3 fails loudly, with the full node-gyp output and Error: not found: make
• npx -y t3@latest --version fails silently, no output on either stream

So the output is being lost somewhere in the npx path specifically, not in the build itself.

Root cause is upstream and currently has no fix in flight. node-pty@1.1.0 runs
node scripts/prebuild.js || node-gyp rebuild, and its npm tarball ships prebuilds for
darwin-arm64, darwin-x64, win32-arm64 and win32-x64 but no linux-x64. The script
says so directly during install:

> Checking prebuilds...
> Rebuilding because directory .../node_modules/node-pty/prebuilds/linux-x64 does not exist

So on Linux it always compiles. node-pty latest is still 1.1.0 (published 2025-12-22), so
^1.1.0 will not float onto a fix.

This is also wider than first install. ensurePinnedRuntimeInstalled runs
npm install --prefix <versionDir> t3@<version>, so every service update recompiles node-pty
too. On a host without a toolchain the install fails and the update path fails the same way.

Workaround for anyone stuck, if you cannot add a compiler to the host (immutable distro, or
you would rather not). Build in a throwaway container that shares the host's glibc, using the
host's own node so the module ABI matches, and write straight into the host's npm prefix:

It has to be two steps. The toolchain must be installed while the container is root, and the
npm install must run as your own uid so it can write your npm prefix.

# 1. throwaway image with a toolchain, matched to your host distro for glibc
cat > /tmp/t3-build.Containerfile <<'EOF'
FROM opensuse/tumbleweed
RUN zypper --non-interactive install --no-recommends gcc-c++ make python3 && zypper clean -a
EOF
podman build -t t3-build -f /tmp/t3-build.Containerfile /tmp

# 2. install as yourself, with your own node, into your own npm prefix
NODE_BIN="$(dirname "$(readlink -f "$(command -v node)")")"
podman run --rm --userns=keep-id --user "$(id -u):$(id -g)" \
  --security-opt label=disable \
  -v "$HOME:$HOME" -e HOME="$HOME" \
  t3-build \
  bash -c "export PATH=$NODE_BIN:\$PATH && npm install -g t3@latest"

On Debian or Ubuntu use FROM debian:stable and
apt-get update && apt-get install -y build-essential python3 in step 1.

Verify the compiled module loads on the host, outside any container:

node -e "require('$(npm root -g)/t3/node_modules/node-pty'); console.log('node-pty ok')"
t3 --version

--security-opt label=disable is needed on SELinux hosts, and --user is needed because
rootless podman otherwise runs the image's root as a different host uid and cannot write your
home. Repeat this for each upgrade until the underlying issue is fixed.

AI Disclosure: Prepared with the assistance of Claude Code (Claude Opus 5). Every command
and output above was run and observed on my own machine. Reviewed by me before posting.

---

Edit: corrected the workaround. The earlier version tried to zypper install inside a
container started with --user, which fails with Root privileges are required. The toolchain
has to go in at image build time instead.

[garysassano]

Another trigger for this, from the opposite direction: a host with a complete C toolchain still fails, if the package manager blocks lifecycle scripts by default.

Environment: WSL2 (Ubuntu), Node 24.19.0, t3@0.0.32 installed via mise's npm backend, which uses aube and passes --ignore-scripts by default. gcc, g++, make and python3 were all present and working.

The failure mode here is different from the one in the report, and I think worth separating, because nothing looks wrong until runtime:

• the install reports success
• the t3 binary materializes and is executable
• t3 --version prints 0.0.32 normally
• the server then dies on boot, after migrations, with NodePtyModuleLoadError

So there is no silence and no failed install to notice — node-pty's install script simply never ran, build/ never gets created, and the package sits there with the four non-Linux prebuilds it ships and nothing else. prebuild.js exiting 1 is precisely what is supposed to hand off to node-gyp rebuild, and that handoff is what gets skipped.

This affects pnpm-style defaults generally, not just mise — any installer that declines lifecycle scripts unless a package is explicitly allowlisted will reproduce it on Linux, since node-pty@1.1.0 has no linux-x64 prebuild to fall back on.

Fix on the mise side is a one-liner, no container needed:

[tools]
t3 = { version = "latest", allow_builds = ["node-pty"] }

After that, node-gyp compiles normally (CXX(target) Release/obj.target/pty/src/unix/pty.o → SOLINK_MODULE(target) Release/pty.node) and the server boots.

One corroboration for the "output is lost in the npx path specifically" point above: on 0.0.32 the installed binary diagnoses this well. The error is fully typed and lists every location it probed:

ERROR (#5): NodePtyModuleLoadError: Failed to load node-pty for linux-x64.
  [cause]: Error: Failed to load native module: pty.node,
  checked: build/Release, build/Debug, prebuilds/linux-x64

That was enough to identify the cause without any guesswork, and looks like #5280 doing its job. The remaining gap really does seem confined to the npx entry point rather than to the diagnostics themselves.

AI disclosure: investigated with Claude Code (Opus 5). Every command, path and output quoted above was run and observed on my machine, and I reviewed this before posting.