[Bug]: t3 server fails to start on linux-arm64 — node-pty has no prebuild and no working source-build fallback

[Bulat-Gumerov]

Before submitting

• I searched existing issues and did not find a duplicate.
• I included enough detail to reproduce or investigate the problem.

Area

apps/server

Steps to reproduce

1. On a linux-arm64 machine (tested: Orange Pi 5 Max, Armbian bookworm, Node v24.15.0), install and run the server with npm i t3@latest (or bun i t3@latest + bunx t3).
2. Start the server: node node_modules/t3/dist/bin.mjs (or npx t3@latest).
3. Observe startup crash after migrations run successfully.

Expected behavior

Server boots and serves the web UI, building node-pty from source if no prebuilt binary exists for the platform (the repo already has this pattern: node-gyp rebuild + staging into prebuilds/linux-<arch> in the WSL/desktop flow).

Actual behavior

Server exits with code 1:

[ERROR]: NodePtyModuleLoadError: Failed to load node-pty for linux-arm64.
[cause]: Error: Failed to load native module: pty.node, checked: build/Release, build/Debug, prebuilds/linux-arm64:
  Error: Cannot find module './prebuilds/linux-arm64//pty.node'

NodePtyAdapter.make ends in .pipe(orDie), so this is an unrecoverable startup crash, not a degraded-terminal warning.

Impact

Blocks work completely

Version or commit

t3@0.0.40 (npm), node-pty@1.1.0 (transitive dep)

Environment

• OS: Armbian 26.11 bookworm (Debian 12), kernel 6.1.115-vendor-rk35xx, aarch64
• Node v24.15.0 (nvm), Bun 1.3.14
• Build tools present: make, gcc, python3 — g++ absent

Logs or stack traces

[14:26:56.384] ERROR (#5): NodePtyModuleLoadError: Failed to load node-pty for linux-arm64.
    at NodePtyAdapter.make (file:///home/uname/node_modules/t3/dist/NodePtyAdapter-B9l4A_UU.mjs:115:34)
  [cause]: Error: Failed to load native module: pty.node, checked: build/Release, build/Debug, prebuilds/linux-arm64:
    Error: Cannot find module './prebuilds/linux-arm64//pty.node'
    Require stack:
    - /home/uname/node_modules/node-pty/lib/utils.js
    - /home/uname/node_modules/node-pty/lib/index.js

Verified on the machine:

• node-pty@1.1.0 npm tarball ships prebuilds/ for darwin-arm64, darwin-x64, win32-arm64, win32-x64 only — no linux prebuild of any arch.
• build/Release/ contains only .deps, node-addon-api, obj.target — the compile never produced pty.node.
• node-pty's own scripts/prebuild.js reports: Rebuilding because .../prebuilds/linux-arm64 does not exist, then the node-gyp rebuild fallback cannot succeed without a C++ compiler (gcc fails with cannot execute 'cc1plus').
• The release pipeline (release.yml) has a build_wsl_node_pty job for linux-x64 only — no linux-arm64 artifact.

Workaround

sudo apt install -y g++ and rebuild (npm rebuild node-pty or a clean npm i so the node scripts/prebuild.js || node-gyp rebuild install script can complete), then run under Node. There is no workaround without a compiler.

Suggested fix (one of)

1. Add a linux-arm64 node-pty build to the release pipeline and bundle/stage it the way the linux-x64 WSL prebuild is handled, or
2. Make the npm t3 install self-healing on Linux: detect missing prebuilds/linux-<arch>/pty.node postinstall and run node-gyp rebuild with a clear error message naming the missing toolchain (g++) instead of crashing at first startup, or
3. At minimum, document g++ (build-essential) as a Linux prerequisite for npx t3 and fail fast with that message during install rather than at server boot.

[Bulat-Gumerov]

Update from upstream research (microsoft/node-pty):

• This is a known upstream gap with a fix already in flight: Prebuilt binary for Linux ARM is actually x86-64 microsoft/node-pty#860 reported that the linux-arm64 prebuild shipped in 1.2.0-beta.2 was actually an x86-64 binary (same Failed to load native module: pty.node ... prebuilds/linux-arm64 crash).
• Fixed by Fix linux arm compiling and add CI for cross-compiled builds microsoft/node-pty#857 (merged 2026-01-06, first released in 1.2.0-beta.4).
• Verified: node-pty@1.2.0-beta.15 tarball now ships both prebuilds/linux-arm64/pty.node (69.1kB) and prebuilds/linux-x64/pty.node.

So the cleanest resolution here may be bumping the server's node-pty dependency from ^1.1.0 (no Linux prebuilds at all) to a ^1.2.0-beta containing the fixed linux-arm64 prebuild, instead of requiring every Linux ARM user to install a C++ toolchain. Note ^1.1.0 will not auto-resolve prerelease versions, so this needs an explicit dependency bump.

[pedrosekine]

Reproduced and verified the fix on a different arm64 platform — Apple Silicon (M2 Air) running Asahi / Arch Linux ARM, Node v26.8.2, t3@0.0.40.

Two data points:

1. Why the source-build fallback fails for some and not others: with a full toolchain present (g++ 16.1), npm i t3@latest compiles node-pty@1.1.0 from source and the server starts fine. The crash is specific to hosts without g++, as in the report above — the fallback isn't broken, it just has an undeclared build-tool requirement.

2. The prebuild bump works. Swapping node-pty@1.2.0-beta.15 into node_modules/t3/node_modules/node-pty (--ignore-scripts, no build/ directory, only the shipped prebuilds/linux-arm64/pty.node, ELF aarch64):

   [19:39:14.637] INFO (#276): Listening on http://127.0.0.1:3773
   

   and a direct node-pty spawn of /bin/sh -c 'uname -m' through that prebuild returns aarch64, exit 0.

So bumping apps/server's node-pty to ^1.2.0-beta.15 resolves this with no code change. Happy to send that one-line bump (+ lockfile) as a PR if you'd take it — otherwise I'll leave it to you. Note the packaged desktop app can't rely on the source-build fallback at all, so the bump is also the prerequisite for a Linux arm64 AppImage (opened an Ideas discussion for that separately).

[Bulat-Gumerov]

Thanks @pedrosekine and @Bulat-Gumerov for the thorough root-cause + cross-platform verification.

Please go ahead with the apps/server node-pty bump to ^1.2.0-beta.15 fix — the evidence here is strong:

• 1.1.0 ships no Linux prebuilds at all, and ^1.1.0 will never auto-resolve the fixed prerelease
• 1.2.0-beta.15 verified working on both Armbian aarch64 (tarball ships prebuilds/linux-arm64/pty.node) and Asahi Arch ARM (server boots, Listening on ..., direct spawn returns aarch64)
• No code change needed, and it is also the prerequisite for any Linux arm64 packaged build that cannot rely on the node-gyp source-build fallback

Happy to review the one-line bump (+ lockfile) PR.

Separate ask: please consider adding automatic dependency management to this repo (Renovate or Dependabot). I checked and there is currently no renovate.json / .renovaterc* / renovate key in package.json, no .github/dependabot.yml, and no update workflow / bot PRs. Something like this class of issue (stale transitive native dep with a fixed upstream release available) would be caught much earlier with it enabled.