| 1 |
# Troubleshooting — GoingsOn |
| 2 |
|
| 3 |
## IMAP Connection Failures |
| 4 |
|
| 5 |
**Symptoms:** Email sync fails, no new emails imported. |
| 6 |
|
| 7 |
1. **Check error in sync logs** (Tauri dev console or app logs) |
| 8 |
|
| 9 |
|
| 10 |
|
| 11 |
| "Connection to {server}:{port} timed out after 30s" | Network/firewall/DNS | Verify server hostname and port, check network, try `telnet server port` | |
| 12 |
| "TLS handshake with {server} timed out after 30s" | TLS issue | Ensure using correct port (993 for IMAPS), check if provider requires specific TLS version | |
| 13 |
| "Login error: ..." | Wrong credentials | Verify username/password. Some providers require app-specific passwords (Gmail, Fastmail) | |
| 14 |
| "XOAUTH2 login error: ..." | OAuth token expired or revoked | Re-authenticate in email account settings. If token was revoked at provider, re-authorize. | |
| 15 |
| "No refresh token available" | OAuth credentials lost from keychain | Re-do OAuth flow in email account settings | |
| 16 |
| "OAuth provider '{id}' not configured" | Missing env vars | Set `GOOGLE_CLIENT_ID`, `MICROSOFT_CLIENT_ID`, etc. | |
| 17 |
| "Select {folder} error: ..." | Folder name wrong | Check folder naming (Gmail uses `[Gmail]/All Mail`, others use `Archive`, `INBOX`, etc.) | |
| 18 |
|
| 19 |
**Timeouts:** All IMAP operations have 30-second timeouts (connect, TLS handshake, login). |
| 20 |
|
| 21 |
## Sync Conflicts |
| 22 |
|
| 23 |
**How conflict resolution works:** Last-write-wins (LWW) by `modified_at` timestamp. Newest edit wins. |
| 24 |
|
| 25 |
|
| 26 |
|
| 27 |
| One device's changes lost | LWW picked the other device's edit | Check `modified_at` timestamps. Manual resolution: edit again on the device you want to win. | |
| 28 |
| Data reverts to older version | Remote pull applied older data | Check sync_state table for `applying_remote` flag stuck at '1'. If stuck, restart app. | |
| 29 |
| Sync stalls mid-pull | DB locked during pull | Close other app instances, restart | |
| 30 |
| Local changes don't appear on other devices | Push failed or changelog empty | Check network to `https://makenot.work`, verify sync credentials in keychain | |
| 31 |
|
| 32 |
**Sync state reset:** |
| 33 |
```sql |
| 34 |
-- Check sync state |
| 35 |
SELECT * FROM sync_state; |
| 36 |
-- If applying_remote stuck: |
| 37 |
UPDATE sync_state SET value='0' WHERE key='applying_remote'; |
| 38 |
``` |
| 39 |
|
| 40 |
## Build Failures |
| 41 |
|
| 42 |
|
| 43 |
|
| 44 |
| `cargo build` fails on macOS | Ensure Xcode CLT installed: `xcode-select --install` | |
| 45 |
| Tauri build fails | Check `src-tauri/tauri.conf.json`, ensure frontend paths exist | |
| 46 |
| Missing shared deps | Ensure `MNW/shared/` exists at correct relative path from workspace | |
| 47 |
| CSS not updating | Edit `styles.css` (never `styles.min.css`), run `build-css.sh` | |
| 48 |
|
| 49 |
## Theme Loading Issues |
| 50 |
|
| 51 |
|
| 52 |
|
| 53 |
| No themes in picker | Bundled themes not in app resources | Check `tauri.conf.json` includes `"../../../MNW/shared/themes/*.toml"` in resources | |
| 54 |
| Theme picker empty in dev | Dev path resolution failed | Ensure `MNW/shared/themes/` exists relative to project root | |
| 55 |
| Custom theme won't load | Malformed TOML | Validate theme file syntax. Required fields: `id`, `name`, `colors` object | |
| 56 |
| Theme import fails | Source file doesn't exist or bad permissions | Verify file path, check directory permissions | |
| 57 |
|
| 58 |
## Database Issues |
| 59 |
|
| 60 |
**Database location:** `~/.local/share/goingson/goingson.db` (platform-dependent) |
| 61 |
|
| 62 |
|
| 63 |
|
| 64 |
| App won't start | DB corrupted or migration failed | Rename `goingson.db` to `.bak`, restart (creates fresh DB). Recover data from sync. | |
| 65 |
| "database is locked" | Multiple app instances or backup tool scanning | Close other instances, exclude DB dir from antivirus | |
| 66 |
| Migration fails on update | Downgrade attempted (older binary on newer schema) | Always upgrade, never downgrade. If stuck, delete DB and re-sync. | |
| 67 |
|
| 68 |
## Keychain Issues |
| 69 |
|
| 70 |
GoingsOn stores OAuth tokens, email passwords, and sync credentials in the OS keychain. |
| 71 |
|
| 72 |
|
| 73 |
|
| 74 |
| macOS | System Keychain | Unlock Keychain in System Preferences. Look for entries starting with "goingson:" | |
| 75 |
| Windows | Credential Manager | Check Settings → Credential Manager for "goingson" entries | |
| 76 |
| Linux | Secret Service (D-Bus) | Ensure service running: `systemctl --user start secrets.service` | |
| 77 |
|
| 78 |
**Keychain keys:** |
| 79 |
- `goingson:oauth:{account_id}` — OAuth refresh tokens |
| 80 |
- `goingson:password:{account_id}` — Email passwords |
| 81 |
- `goingson:sync:token` — SyncKit auth token |
| 82 |
|
| 83 |
## Error Codes |
| 84 |
|
| 85 |
All Tauri command errors return structured `ApiError` with a code: |
| 86 |
|
| 87 |
|
| 88 |
|
| 89 |
| `NOT_FOUND` | Resource doesn't exist | Invalid task/event/project ID | |
| 90 |
| `VALIDATION_ERROR` | Input validation failed | Empty description, string too long, invalid date | |
| 91 |
| `DATABASE_ERROR` | SQLite error | Corruption, schema mismatch, locked DB | |
| 92 |
| `AUTH_ERROR` | Auth failed | Wrong password, expired token | |
| 93 |
| `EXTERNAL_SERVICE_ERROR` | IMAP/SMTP/sync server failed | Network, timeout, server down | |
| 94 |
| `PARSE_ERROR` | Parsing failed | Invalid date format, malformed ICS/VCF | |
| 95 |
|