# Troubleshooting — GoingsOn

## IMAP Connection Failures

**Symptoms:** Email sync fails, no new emails imported.

1. **Check error in sync logs** (Tauri dev console or app logs)

| Error Message | Cause | Fix |
|---------------|-------|-----|
| "Connection to {server}:{port} timed out after 30s" | Network/firewall/DNS | Verify server hostname and port, check network, try `telnet server port` |
| "TLS handshake with {server} timed out after 30s" | TLS issue | Ensure using correct port (993 for IMAPS), check if provider requires specific TLS version |
| "Login error: ..." | Wrong credentials | Verify username/password. Some providers require app-specific passwords (Gmail, Fastmail) |
| "XOAUTH2 login error: ..." | OAuth token expired or revoked | Re-authenticate in email account settings. If token was revoked at provider, re-authorize. |
| "No refresh token available" | OAuth credentials lost from keychain | Re-do OAuth flow in email account settings |
| "OAuth provider '{id}' not configured" | Missing env vars | Set `GOOGLE_CLIENT_ID`, `MICROSOFT_CLIENT_ID`, etc. |
| "Select {folder} error: ..." | Folder name wrong | Check folder naming (Gmail uses `[Gmail]/All Mail`, others use `Archive`, `INBOX`, etc.) |

**Timeouts:** All IMAP operations have 30-second timeouts (connect, TLS handshake, login).

## Sync Conflicts

**How conflict resolution works:** Last-write-wins (LWW) by `modified_at` timestamp. Newest edit wins.

| Symptom | Cause | Fix |
|---------|-------|-----|
| 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. |
| 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. |
| Sync stalls mid-pull | DB locked during pull | Close other app instances, restart |
| Local changes don't appear on other devices | Push failed or changelog empty | Check network to `https://makenot.work`, verify sync credentials in keychain |

**Sync state reset:**
```sql
-- Check sync state
SELECT * FROM sync_state;
-- If applying_remote stuck:
UPDATE sync_state SET value='0' WHERE key='applying_remote';
```

## Build Failures

| Issue | Fix |
|-------|-----|
| `cargo build` fails on macOS | Ensure Xcode CLT installed: `xcode-select --install` |
| Tauri build fails | Check `src-tauri/tauri.conf.json`, ensure frontend paths exist |
| Missing shared deps | Ensure `MNW/shared/` exists at correct relative path from workspace |
| CSS not updating | Edit `styles.css` (never `styles.min.css`), run `build-css.sh` |

## Theme Loading Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| No themes in picker | Bundled themes not in app resources | Check `tauri.conf.json` includes `"../../../MNW/shared/themes/*.toml"` in resources |
| Theme picker empty in dev | Dev path resolution failed | Ensure `MNW/shared/themes/` exists relative to project root |
| Custom theme won't load | Malformed TOML | Validate theme file syntax. Required fields: `id`, `name`, `colors` object |
| Theme import fails | Source file doesn't exist or bad permissions | Verify file path, check directory permissions |

## Database Issues

**Database location:** `~/.local/share/goingson/goingson.db` (platform-dependent)

| Symptom | Cause | Fix |
|---------|-------|-----|
| App won't start | DB corrupted or migration failed | Rename `goingson.db` to `.bak`, restart (creates fresh DB). Recover data from sync. |
| "database is locked" | Multiple app instances or backup tool scanning | Close other instances, exclude DB dir from antivirus |
| Migration fails on update | Downgrade attempted (older binary on newer schema) | Always upgrade, never downgrade. If stuck, delete DB and re-sync. |

## Keychain Issues

GoingsOn stores OAuth tokens, email passwords, and sync credentials in the OS keychain.

| Platform | Service | Fix |
|----------|---------|-----|
| macOS | System Keychain | Unlock Keychain in System Preferences. Look for entries starting with "goingson:" |
| Windows | Credential Manager | Check Settings → Credential Manager for "goingson" entries |
| Linux | Secret Service (D-Bus) | Ensure service running: `systemctl --user start secrets.service` |

**Keychain keys:**
- `goingson:oauth:{account_id}` — OAuth refresh tokens
- `goingson:password:{account_id}` — Email passwords
- `goingson:sync:token` — SyncKit auth token

## Error Codes

All Tauri command errors return structured `ApiError` with a code:

| Code | Meaning | Common Cause |
|------|---------|-------------|
| `NOT_FOUND` | Resource doesn't exist | Invalid task/event/project ID |
| `VALIDATION_ERROR` | Input validation failed | Empty description, string too long, invalid date |
| `DATABASE_ERROR` | SQLite error | Corruption, schema mismatch, locked DB |
| `AUTH_ERROR` | Auth failed | Wrong password, expired token |
| `EXTERNAL_SERVICE_ERROR` | IMAP/SMTP/sync server failed | Network, timeout, server down |
| `PARSE_ERROR` | Parsing failed | Invalid date format, malformed ICS/VCF |