Troubleshooting Fixes for common install, auth, billing, packaging, and update issues.
Mode note: This page documents shared product behavior and the existing Standalone provider details. Unified builds keep the same UI through backend-neutral services and use the provider configuration in Unified / Soar API Setup . Configuration errors never fall back silently.
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 depsNode/toolchain mismatch Use Node `^20.19 Wrong pnpm version packageManager pin not honoredEnable 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 launchAuth 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 uploadedVerify 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 offEnable 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 unsetThe hook no-ops without credentials (unsigned build); set APPLE_ID/APPLE_APP_SPECIFIC_PASSWORD/APPLE_TEAM_ID. See Packaging . snap target failsBuilding 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 .
