Skip to content

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

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

Description

@Bulat-Gumerov
Bulat-Gumerov
opened on Sep 13, 2026

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.

Activity

  1. Bulat-Gumerov commented on Sep 13, 2026

    @Bulat-Gumerov
    Bulat-Gumerov
    on Sep 13, 2026
    Author

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

    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.

  2. pedrosekine commented on Sep 13, 2026

    @pedrosekine
    pedrosekine
    on 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:

    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).

  3. Bulat-Gumerov commented on Sep 14, 2026

    @Bulat-Gumerov
    Bulat-Gumerov
    on Sep 14, 2026
    Author

    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.

  4. Yash-Singh1
    closed this as completedin #13748on Sep 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions