# Troubleshooting — Balanced Breakfast

## Plugin Fetch Failures

**Symptoms:** Feed shows yellow (degraded) or red (circuit broken) status.

### Error Categories

| Category | Causes | Auto-Retry | Circuit Break |
|----------|--------|-----------|---------------|
| **Transient** | DNS timeout, HTTP 500/502/503 | Yes | After 10 failures |
| **RateLimited** | HTTP 429 | Yes (after delay) | Never |
| **Auth** | HTTP 401/403, invalid API key | No | Immediate |
| **Config** | HTTP 404/410, bad URL, missing field | No | Immediate |
| **Parse** | Malformed RSS/JSON/XML | Yes | After 10 failures |

### Decision Tree

1. **Feed shows red (circuit broken)?**
   - Check `last_error` in feed details for the error category
   - **Auth error** → Fix API key/credentials in feed config, then "Reset & Retry"
   - **Config error** → Verify feed URL exists and is accessible, delete and re-add
   - **10+ transient failures** → Wait for service recovery, then "Reset & Retry"

2. **Feed shows yellow (degraded)?**
   - System retries automatically
   - If persistent: verify URL, check API key, try manual retry

3. **Feed never updates?**
   - Plugin `.rhai` file missing from `plugins/` → restart app
   - Auto-fetch disabled → check settings
   - Circuit breaker tripped → see above

## Circuit Breaker

- **Threshold:** 10 consecutive failures for transient/parse errors. Auth/config errors trip immediately.
- **Rate-limited errors** do NOT increment the failure counter.
- **Reset:** Feed menu → "Reset & Retry" (calls `reset_circuit_breaker_and_fetch`)
- **What reset does:** Sets `circuit_broken=false`, `consecutive_failures=0`, clears `last_error`, attempts fresh fetch

## OPML Import Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Invalid OPML: ..." | Malformed XML | Validate OPML syntax (must be valid XML with `<outline>` elements) |
| URLs skipped | Non-http/https URLs in OPML | Edit OPML to use only http/https URLs |
| Feeds already exist | Duplicate URLs | Expected — `skipped` counter shows how many were duplicates |
| Import result shows errors | Database or URL validation failures | Check error messages in import result, fix individual URLs |

**Import result format:** `{ imported: N, skipped: N, errors: [...] }`

## Secret Decryption Failures

**Symptoms:** Feeds with API keys show auth errors despite correct credentials.

**Encryption scheme:** AES-256-GCM, format `bb_enc:v1:<base64(nonce || ciphertext || tag)>`

| Symptom | Cause | Fix |
|---------|-------|-----|
| Feed auth errors after OS reinstall | Encryption key lost from keychain | Delete feeds, re-add with credentials (auto-encrypts on save) |
| "Decryption failed" in logs | Wrong key or corrupted ciphertext | Delete `~/.config/balanced-breakfast/encryption.key`, restart (generates new key). Re-add feeds. |
| Keychain unavailable | macOS Keychain locked, Linux Secret Service not running | Unlock keychain or start D-Bus Secret Service |

**Key storage priority:**
1. OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
2. Fallback: `~/.config/balanced-breakfast/encryption.key` (file, 0600 permissions)

**Backward compatibility:** Unencrypted secret values pass through on decrypt and get encrypted on next config change.

## Plugin Sandbox Violations

| Error | Limit | Fix |
|-------|-------|-----|
| "Script execution exceeded operation limit" | 100,000 operations per fetch | Plugin has infinite loop or very inefficient logic |
| "Max recursion level exceeded" | 32 call levels | Refactor plugin to iterative approach |
| "HTTP request limit exceeded" | 100 requests per fetch | Plugin making too many HTTP calls |
| "Fetch timeout exceeded" | 60s aggregate per fetch | Plugin spending too long overall |
| "Blocked request to internal address" | localhost/private IPs blocked | Plugin trying SSRF — use public URLs only |

**Per-request timeout:** 15 seconds. **Response size limit:** 2 MB.

## Database Issues

**Database location:** `~/.local/share/balanced-breakfast/` (platform-dependent), SQLite via sqlx.

| Symptom | Fix |
|---------|-----|
| App won't start, migration error | Delete DB file, restart (fresh DB, re-sync from cloud) |
| "database is locked" | Close other app instances, exclude DB from antivirus |
| FTS5 search returns no results | Rebuild FTS index: delete `feed_items_fts` table, restart app |

## Sync Issues

Same SyncKit integration as GoingsOn:
- Credentials stored in OS keychain
- Push/pull with changelog triggers
- `applying_remote` flag can get stuck — restart app to clear
- Sync interval: 15 minutes (configurable)

**What syncs:** Feed subscriptions, feed tags, user config, query feeds, item read/star state. Item content does NOT sync (fetched independently per device).

## Error Codes

| Code | Meaning |
|------|---------|
| `BAD_REQUEST` | Invalid input (bad OPML, missing field) |
| `NOT_FOUND` | Feed or resource doesn't exist |
| `DATABASE` | SQLite error |
| `INTERNAL` | Unexpected error |
| `PLUGIN` | Rhai plugin error (sandbox violation, runtime error) |