[Bug]: Nightly desktop backend crash-loops due to missing ffi-rs native optional dependency (WORKAROUND INCLUDED)

[StiensWout]

Summary

Windows nightly desktop builds can launch the Electron shell but never open the main app window because the packaged backend crash-loops before readiness.

The backend stderr in %USERPROFILE%\.t3\userdata\logs\server-child.log shows:

Error: Cannot find module '@yuuang/ffi-rs-win32-x64-msvc'
Require stack:
- ...\resources\app.asar\node_modules\ffi-rs\index.js

Environment

• OS: Windows
• App: T3 Code nightly desktop build
• Backend Node: v24.15.0

Root Cause

Current main includes @ff-labs/fff-node in apps/server, which depends on ffi-rs.

ffi-rs resolves its platform binary through optional dependencies, including:

• @yuuang/ffi-rs-win32-x64-msvc

The desktop artifact build stages production dependencies with:

vp install --prod --no-optional

That excludes the native optional package from the packaged app. On Windows, ffi-rs then fails at startup, the backend exits with code 1, and the desktop window is never created because backend readiness is never reached.

Expected Behavior

The Windows desktop package includes the native optional dependency needed by ffi-rs, so the backend reaches readiness and the main window opens.

Actual Behavior

The backend repeatedly exits with MODULE_NOT_FOUND for @yuuang/ffi-rs-win32-x64-msvc.

Suggested Fix

Do not pass --no-optional when installing staged desktop production dependencies. Platform-native optional packages are required runtime dependencies for packages like ffi-rs.

[StiensWout]

Will open a PR with fix next :)

[Inovvia]

It also crashes on my mac

[carlrosell]

I’m having the same issue. Could this be related to the same underlying cause as #3080?

[allisonmahmood]

Confirming on macOS / Apple Silicon (darwin-arm64), nightly 0.0.28-nightly.20260616.571.

server-child.log shows the same crash, with the darwin variant of the module:

Error: Cannot find module '@yuuang/ffi-rs-darwin-arm64'
Require stack:
- .../T3 Code.app/Contents/Resources/app.asar/node_modules/ffi-rs/index.js

ffi-rs@1.3.2 is bundled, but no @yuuang/* optional binary is present anywhere in the app (neither in app.asar nor app.asar.unpacked). The backend exits with code=1 and restarts every ~10s, so the
window never reaches readiness — same failure as Windows, just the darwin-arm64 optional dep instead of win32-x64-msvc. So #3105 (dropping --no-optional) should fix macOS too.

Workaround: switching the desktop update channel from nightly to latest fixes it — the current stable release (0.0.27) predates the ffi-rs dependency, so it launches normally. (If you're already on
the broken nightly, you may need to reinstall the stable build as well, since the latest channel won't downgrade on its own.)

[Atchferox]

This is nice for us european user's @t3dotgg and @juliusmarminge are probably sleeping, but everybody on the latest nightly currently is in a broken state :(

[allisonmahmood]

Workaround for macOS (verified on Apple Silicon, nightly 0.0.28-nightly.20260616.571)

On macOS you can't fix this by dropping the missing optional dep into the app bundle: App Management protection blocks writing inside the notarized .app in /Applications, and even a copy in your home
folder can't be re-signed after editing — macOS then flags it "damaged and can't be opened."

What does work is supplying the module out-of-bundle via NODE_PATH. Electron's asar-aware resolver only searches node_modules paths inside the bundle, but it still honors NODE_PATH, and the packaged
backend runs as a child process that inherits it.

# 1. Install the platform binary that ffi-rs needs.
#    Match the bundled ffi-rs version (it's 1.3.2 in this nightly).
#    Apple Silicon:
npm install --prefix ~/.t3code-shim @yuuang/ffi-rs-darwin-arm64@1.3.2
#    Intel Macs: use @yuuang/ffi-rs-darwin-x64@1.3.2 instead.

# 2. Make GUI-launched apps inherit NODE_PATH so the backend child can resolve it.
#    (Use $HOME, not ~ — launchctl does not expand tilde.)
launchctl setenv NODE_PATH "$HOME/.t3code-shim/node_modules"

# 3. Fully quit T3 Code, then reopen it normally (Dock/Spotlight).

After this the backend reaches readiness instead of crash-looping — backend ready, and http://127.0.0.1:3773/ returns 200 — and the main window opens.

Notes

• launchctl setenv only lasts for the current login session. After a reboot, re-run step 2 and relaunch the app.
• Once a nightly including fix: include optional deps in desktop package #3105 ships (it bundles the optional dep), this is no longer needed. Clean up with:

  launchctl unsetenv NODE_PATH
  rm -rf ~/.t3code-shim

[StiensWout]

Workarounds while waiting for a nightly with #3105

The packaged app has ffi-rs@1.3.2, but the platform-specific optional package is missing from the bundle. Until a fixed nightly ships, one workaround is to provide that package out-of-bundle via NODE_PATH.

WINDOWS WORKAROUND

Use this if your logs mention a missing Windows package such as @yuuang/ffi-rs-win32-x64-msvc.

PowerShell:

# Windows x64:
npm install --prefix "$env:USERPROFILE\.t3code-shim" "@yuuang/ffi-rs-win32-x64-msvc@1.3.2"

# Windows ARM64 users should use this package instead:
# npm install --prefix "$env:USERPROFILE\.t3code-shim" "@yuuang/ffi-rs-win32-arm64-msvc@1.3.2"

$shim = "$env:USERPROFILE\.t3code-shim\node_modules"
$current = [Environment]::GetEnvironmentVariable("NODE_PATH", "User")

if ([string]::IsNullOrWhiteSpace($current)) {
  [Environment]::SetEnvironmentVariable("NODE_PATH", $shim, "User")
} elseif (($current -split ";") -notcontains $shim) {
  [Environment]::SetEnvironmentVariable("NODE_PATH", "$shim;$current", "User")
}

Then fully quit T3 Code and reopen it. If launching from Start/Menu still crash-loops, sign out and back in, or restart Windows, so GUI-launched apps pick up the updated user environment.

Windows cleanup after a fixed nightly ships:

$shim = "$env:USERPROFILE\.t3code-shim\node_modules"
$current = [Environment]::GetEnvironmentVariable("NODE_PATH", "User")
$remaining = (($current -split ";") | Where-Object { $_ -and $_ -ne $shim }) -join ";"

if ($remaining) {
  [Environment]::SetEnvironmentVariable("NODE_PATH", $remaining, "User")
} else {
  [Environment]::SetEnvironmentVariable("NODE_PATH", $null, "User")
}

Remove-Item -Recurse -Force "$env:USERPROFILE\.t3code-shim"

MACOS WORKAROUND

Use this if your logs mention a missing macOS package such as @yuuang/ffi-rs-darwin-arm64 or @yuuang/ffi-rs-darwin-x64.

Do not modify the .app bundle. Install the missing platform package outside the app and expose it with NODE_PATH:

case "$(uname -m)" in
  arm64) pkg="@yuuang/ffi-rs-darwin-arm64@1.3.2" ;;
  x86_64) pkg="@yuuang/ffi-rs-darwin-x64@1.3.2" ;;
  *) echo "Unsupported Mac architecture: $(uname -m)" >&2; exit 1 ;;
esac

npm install --prefix "$HOME/.t3code-shim" "$pkg"
launchctl setenv NODE_PATH "$HOME/.t3code-shim/node_modules"

Fully quit T3 Code, then reopen it normally.

macOS cleanup after a fixed nightly ships:

launchctl unsetenv NODE_PATH
rm -rf "$HOME/.t3code-shim"