Troubleshooting
Fixes for common install, auth, billing, packaging, and update issues.
Symptom → likely cause → fix, grouped by area. Each entry links back to the guide
that owns the subsystem. When in doubt, open the Logs
page (or run pnpm dev with devtools) — most failures log a clear reason.
| Symptom | Likely cause | Fix |
|---|
postinstall fails on native deps | Node/toolchain mismatch | Use Node `^20.19 |
| Wrong pnpm version | packageManager pin not honored | Enable corepack or install pnpm 11.1.3. See Installation. |
| Port already in use | A stale pnpm dev | Stop the other process; scripts/dev.mjs owns the dev port. |
| Blank window / renderer crash | A renderer exception before mount | Run pnpm dev and open devtools; check the console and the Logs page. The ErrorBoundary should show a themed fallback. |
| Symptom | Likely cause | Fix |
|---|
SupabaseConfigErrorScreen on launch | Auth on but Supabase env missing/invalid | Set VITE_SUPABASE_URL + VITE_SUPABASE_PUBLISHABLE_KEY, or set VITE_AUTH_ENABLED=false. See Authentication. |
| Email confirmation / reset never returns to the app | Deep-link scheme not registered, or redirect URL not allow-listed in Supabase | Confirm the soar-electron:// handler is registered and add the redirect URL under Supabase → Auth → URL Configuration. See Deep Links. |
Deep link works packaged but not in dev | Dev protocol registration is per-platform and flaky | Verify against a pnpm build:unpack build. See Deep Links. |
| Sign-in doesn't persist across restart | safeStorage encryption unavailable (e.g. no Linux keyring) | Ensure an OS keyring is available; a SecureStorageError (ENCRYPTION_UNAVAILABLE) is logged. See Settings Store. |
| Symptom | Likely cause | Fix |
|---|
| No Billing UI / features stay locked | Billing flag off | Set VITE_BILLING_ENABLED=true. See Billing. |
| Checkout opens but nothing unlocks | Product IDs unset, or the webhook never wrote the row | Set VITE_CREEM_PRODUCT_*; confirm the subscriptions row appears. See Creem Setup. |
| Entitlement never updates | Reading local purchase state instead of Supabase | Entitlement is read only from the subscriptions table (RLS SELECT-only). See Billing. |
| Webhook signature failures | Wrong CREEM_WEBHOOK_SECRET | Re-set the Edge secret; it lives only as a Supabase secret, never in the app .env. See Creem Setup. |
| Symptom | Likely cause | Fix |
|---|
| Notifications silent on Windows | AUMID not set, or running unpackaged | The template sets APP_USER_MODEL_ID at startup; Windows toasts are most reliable from an installed build. Confirm settings.notifications is on. See Notifications & Shortcuts. |
| A shortcut does nothing | Accelerator conflict, or a non-global scope | Check the startup warning about duplicate accelerators; only global-scope shortcuts register system-wide, and none ship by default. See Notifications & Shortcuts. |
| Window opens off-screen | Stale saved bounds | The store re-centers invalid bounds automatically; delete window-state.json in userData if needed. See Windows, Menus & Tray. |
| External link opened in-app or blocked | Not https:/mailto: | openExternal only allows those schemes. See Windows, Menus & Tray. |
| Symptom | Likely cause | Fix |
|---|
| Update check errors with a feed 404 | UPDATE_SERVER_URL wrong, or latest*.yml not uploaded | Verify the feed URL and that the metadata + installer + blockmap are hosted. See Auto Update. |
| macOS won't apply an update | Build isn't signed + notarized | Gatekeeper rejects unsigned replacements; sign and notarize. See Packaging. |
No updates in dev | Updater is a no-op unpackaged | Test updates against a packaged build. See Auto Update. |
| No update UI at all | VITE_AUTO_UPDATE_ENABLED=false, or the autoUpdate setting is off | Enable the flag and toggle auto-update in Settings → Updates. |
| Symptom | Likely cause | Fix |
|---|
| Wrong or missing app icon | Source SVGs edited but rasters not regenerated | Re-run the docs/APP_ICONS.md recipe. See Packaging. |
| Notarization fails or is skipped | APPLE_* env unset | The hook no-ops without credentials (unsigned build); set APPLE_ID/APPLE_APP_SPECIFIC_PASSWORD/APPLE_TEAM_ID. See Packaging. |
snap target fails | Building Linux targets off-Linux | Build Linux artifacts on Linux (or CI); trim the target list to what you ship. |
| Windows SmartScreen warning | Unsigned installer | Provide CSC_LINK/CSC_KEY_PASSWORD; an EV cert clears reputation instantly. |
| Symptom | Likely cause | Fix |
|---|
A raw key like nav.home renders | Missing translation key | Add the key to both app/locales/en/*.json and app/locales/zh/*.json. See Internationalization. |
