Troubleshooting

Troubleshooting

---

App won't start

Symptom	Fix
Blank window on first launch	Wait 10–30s for IndexedDB init; restart once
SmartScreen warning	Expected for unsigned builds — click "More info" → Run
npm run build fails	Run npm ci first; use Node 20+

---

Data issues

Symptom	Fix
Habits disappeared	Check %APPDATA%/Cultiva wasn't deleted; restore from Settings → Backup ZIP/JSON
Settings reset	Portable vs installed builds use different userData paths

Export regularly: Settings → Backup → Export JSON/ZIP/iCal.

---

Plugin issues

Install fails or rolls back

1. Open DevTools (Ctrl+Shift+I).
2. Look for [PluginManager] or sandbox errors.
3. Verify Cultiva version ≥ plugin minAppVersion (1.7.0 for current registry).
4. Confirm registry URL:

   https://raw.githubusercontent.com/krwg/cultiva-plugins/main/registry.json
   

Common causes:

• onEnable blocks too long (network before returning) → sandbox timeout
• sha256 mismatch → re-fetch registry or update Cultiva
• Missing permission in manifest (e.g. network for weather)

Plugin installed but invisible

• Master Plugins toggle must be ON.
• Header plugins appear in the top bar; garden plugins in the garden view.
• Some plugins need a click on the header chip to open UI.

Plugin removed itself after restart

If sandbox init fails, Cultiva may silently remove the plugin id from the install list (console warning only). Reinstall from catalog; check DevTools for the root error.

Weather wrong location

• Pick city from the Weather sheet (header chip), not only the Settings text field.
• Settings "City" string alone does not update lat/lon in 1.7.0 — known bug.

Time / Weather search loses focus

Typing in city or timezone search rebuilds the entire sheet each keystroke — known UX bug. Type slowly or use popular city buttons.

Radio won't autoplay on startup

Browser autoplay policy blocks audio.play() without user gesture. Click the header chip and press Play once.

Pomodoro sheet has no backdrop

Install Weather or Time alongside Pomodoro, or wait for shared sheet CSS in Cultiva core.

Plugins still run when disabled

Master toggle off removes header items but may not destroy sandboxes in 1.7.0 — restart app or uninstall problematic plugins until fixed.

---

Performance

Symptom	Fix
High CPU with ambient background	Switch to a lighter background or static custom photo
Slow plugin catalog	Registry fetched from GitHub — check network

---

Getting help

1. Search existing issues.
2. Include: Cultiva version, Windows version, plugin id, DevTools console excerpt.
3. Security issues: see SECURITY.md — do not open public issues for vulnerabilities.