Troubleshooting

A collection of production-running gotchas and how to handle them. Read Deployment and Configuration first for context.

Cross-compiled binary uses ∞ GB on Linux

A Bun binary built on macOS with --target=bun-linux-x64 has a broken JSC heap on Linux. Build natively on the Linux host with bun run build:bin instead. The native build settles around 80 MB resident.

systemd SystemCallFilter blocks startup (status=31/SYS)

SystemCallFilter=~@resources kills syscalls Bun's JIT needs (e.g. sched_setaffinity); drop it. MemoryDenyWriteExecute also breaks JSC. packaging/typress.service ships only the directives that don't trip these.

ProtectHome=true breaks the binary

isomorphic-dompurify pulls in jsdom, which loads default-stylesheet.css via __dirname at startup. Building under /home bakes a /home/.../node_modules/... path into the binary, and ProtectHome rejects it with EACCES. Build outside /home (e.g. /var/lib/typress-build) to fix it.

Admin returns invalid_input on every action

v0.1.x changed every destructive admin endpoint to take a {password, totp?} envelope (ADR-005). A cached old admin SPA still posting flat bodies will see invalid_input. Hard-reload (Cmd+Shift+R / Ctrl+Shift+R) to pick up the new bundle.

Theme reinstall fails with EACCES

0.1.x's theme uninstall didn't actually delete the on-disk files, so reinstalling the same id+version tried to overwrite a 0o444 (read-only) index.js. 0.1.4+ removes the directory at uninstall time. If you upgraded from an earlier version, sudo rm -rf the stale theme directory once.

Saving site settings cleared the nav

The Settings page replaces site.nav wholesale. Hitting Save without any nav rows leaves it as []. Other singleton fields like navStyle.cta have the same risk — confirm the existing values are visible on the page before saving.