Repository navigation
[Bug]: t3 server fails to start on linux-arm64 — node-pty has no prebuild and no working source-build fallback #11556
Description
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
- 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(orbun i t3@latest+bunx t3). - Start the server:
node node_modules/t3/dist/bin.mjs(ornpx t3@latest). - 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.0npm tarball shipsprebuilds/fordarwin-arm64, darwin-x64, win32-arm64, win32-x64only — no linux prebuild of any arch.build/Release/contains only.deps, node-addon-api, obj.target— the compile never producedpty.node.node-pty's ownscripts/prebuild.jsreports:Rebuilding because .../prebuilds/linux-arm64 does not exist, then thenode-gyp rebuildfallback cannot succeed without a C++ compiler (gccfails withcannot execute 'cc1plus').- The release pipeline (
release.yml) has abuild_wsl_node_ptyjob 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)
- Add a linux-arm64
node-ptybuild to the release pipeline and bundle/stage it the way the linux-x64 WSL prebuild is handled, or - Make the npm
t3install self-healing on Linux: detect missingprebuilds/linux-<arch>/pty.nodepostinstall and runnode-gyp rebuildwith a clear error message naming the missing toolchain (g++) instead of crashing at first startup, or - At minimum, document
g++(build-essential) as a Linux prerequisite fornpx t3and fail fast with that message during install rather than at server boot.
Reacted by Michael DeMarti
Activity
Bulat-Gumerov commentedon Sep 13, 2026
Update from upstream research (microsoft/node-pty):
linux-arm64prebuild shipped in1.2.0-beta.2was actually an x86-64 binary (sameFailed to load native module: pty.node ... prebuilds/linux-arm64crash).1.2.0-beta.4).node-pty@1.2.0-beta.15tarball now ships bothprebuilds/linux-arm64/pty.node(69.1kB) andprebuilds/linux-x64/pty.node.So the cleanest resolution here may be bumping the server's
node-ptydependency from^1.1.0(no Linux prebuilds at all) to a^1.2.0-betacontaining the fixed linux-arm64 prebuild, instead of requiring every Linux ARM user to install a C++ toolchain. Note^1.1.0will not auto-resolve prerelease versions, so this needs an explicit dependency bump.pedrosekine commentedon Sep 13, 2026
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:
Why the source-build fallback fails for some and not others: with a full toolchain present (
g++16.1),npm i t3@latestcompilesnode-pty@1.1.0from source and the server starts fine. The crash is specific to hosts withoutg++, as in the report above — the fallback isn't broken, it just has an undeclared build-tool requirement.The prebuild bump works. Swapping
node-pty@1.2.0-beta.15intonode_modules/t3/node_modules/node-pty(--ignore-scripts, nobuild/directory, only the shippedprebuilds/linux-arm64/pty.node, ELF aarch64):and a direct
node-ptyspawn of/bin/sh -c 'uname -m'through that prebuild returnsaarch64, exit 0.So bumping
apps/server'snode-ptyto^1.2.0-beta.15resolves 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 commentedon Sep 14, 2026
Thanks @pedrosekine and @Bulat-Gumerov for the thorough root-cause + cross-platform verification.
Please go ahead with the
apps/servernode-ptybump to^1.2.0-beta.15fix — the evidence here is strong:1.1.0ships no Linux prebuilds at all, and^1.1.0will never auto-resolve the fixed prerelease1.2.0-beta.15verified working on both Armbian aarch64 (tarball shipsprebuilds/linux-arm64/pty.node) and Asahi Arch ARM (server boots,Listening on ..., direct spawn returnsaarch64)node-gypsource-build fallbackHappy 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*/renovatekey inpackage.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.