Troubleshooting
Common desktop-template failures, causes, and fixes.
Use this as a quick symptom → cause → fix index. The Logs
page and pnpm dev terminal are the first places to look for the underlying error.
| Symptom | Likely cause | Fix |
|---|
| Rust or webview dependency error | Missing platform prerequisites | Install Rust plus the macOS CLT, Windows MSVC/WebView2, or Linux WebKitGTK/AppIndicator packages. See Installation. |
First pnpm dev seems stuck | Initial Rust compilation | Wait for the first crate build; later builds are incremental. |
| Port 1420 is in use | Another Vite process is running | Stop the other process, or free the port configured as devUrl. |
| Blank window | Frontend exception, CSP problem, or unavailable webview | Run pnpm dev, inspect its output and Logs, then check the themed error fallback. |
| WebView2 missing | Windows runtime is unavailable | Install WebView2; the bundled installer uses the download bootstrapper. |
| Symptom | Likely cause | Fix |
|---|
SupabaseConfigErrorScreen | Auth is on while the Supabase URL/key are missing or invalid | Set VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY, or disable auth. See Authentication. |
| Auth or billing return does not open the app | Scheme is not registered, or redirect is not configured | Check the rebranded scheme in tauri.conf.json and Supabase Auth URL Configuration. On Windows development, test an installed build or use the documented run-once workaround. See Deep Links. |
| Billing is absent or locked | Flag, product IDs, webhook, or entitlement row is missing | Enable VITE_BILLING_ENABLED, set product IDs, then confirm the webhook writes subscriptions. See Creem Setup. |
| Webhook signature fails | Wrong Edge secret | Reset CREEM_WEBHOOK_SECRET with supabase secrets set; it must not be in app .env. |
| Symptom | Likely cause | Fix |
|---|
Keychain prompt or ENCRYPTION_UNAVAILABLE | OS keychain is unavailable, or macOS asks for unsigned-dev access | Ensure a working OS keychain; accept the expected macOS development prompt. See Settings Store. |
| Linux tray missing | AppIndicator dependencies are absent or the desktop environment lacks tray support | Install the AppIndicator prerequisites and test on a tray-capable desktop environment. |
| Bindings-drift CI failure | Rust command types changed without committed bindings | Run cargo test --manifest-path src-tauri/Cargo.toml, review src/lib/bindings.ts, and commit the generated change. |
| Raw translation key renders | Locale key is missing | Add it to both EN and ZH locale files and namespace registration. See Internationalization. |
| Symptom | Likely cause | Fix |
|---|
| Gatekeeper says the app is damaged or blocked | macOS build is unsigned or not notarized | Sign and notarize the distribution build; development builds are not a distribution test. See Packaging. |
| SmartScreen warning | Windows installer lacks reputation or signing | Sign with WINDOWS_CERTIFICATE; an EV certificate earns immediate reputation. |
| Update signature mismatch | Feed was signed by a different private key than the configured public key | Rebuild/sign with the matching minisign key pair and publish matching artifacts. See Auto-Update. |
| Update check cannot reach the feed | Wrong endpoint or missing manifest/artifact | Check runtime/build UPDATE_SERVER_URL, latest.json, and every URL/signature in it. |
| Linux package does not self-update | The installed format is deb or rpm | Use the distribution's package manager or manual download; only AppImage is supported by the updater. |
