PonderOS Troubleshooting Guide

Common issues and how to fix them 🔧

#🤖 AI Chat Issues

#Lumen isn't responding to my questions

Symptoms:

Chat input works but no response appears
Spinning loader that never completes
Error message about API limits

Solutions:

Check your API quota (Free plan):
- Free users get 50 queries/month
- Check usage: Settings → Usage
- If over limit → upgrade to Pro or wait for monthly reset
Verify API key (self-hosted):
- Settings → AI Configuration
- Make sure OpenAI or Anthropic key is valid
- Test: echo $OPENAI_API_KEY (should show your key)
Check internet connection:
- AI queries require internet (even in local mode)
- Test: Can you access https://openai.com?

Clear cache and restart:

# macOS/Linux
rm -rf ~/.ponderos/cache

# Windows
del /s /q %APPDATA%\ponderos\cache

Then restart PonderOS

#Lumen gives incorrect or incomplete answers

Common causes:

Not enough context in your vault:
- Lumen can only search what you've saved
- Try: "Search the web for [topic] and save to vault"
Query too vague:
- ❌ "What's the status?"
- ✅ "What's the status of the mobile redesign project?"
Out-of-date information:
- Lumen's training data has a cutoff
- For current info: explicitly ask for web search
- Example: "Search the web for latest GPT-5 news"

Pro tip: Be specific. Include project names, dates, people.

#📝 Document Issues

#Documents not saving

Symptoms:

Changes disappear after closing
"Unsaved changes" warning persists
Error: "Failed to save document"

Solutions:

Manual save:
- Press Cmd/Ctrl+S after every edit
- Or enable auto-save: Settings → Editor → Auto-save (every 30s)
Check disk space (local mode):
```
df -h  # macOS/Linux
```
- Need at least 1GB free for vault operations

Permissions issue (local mode):

# macOS/Linux
chmod -R 755 ~/.ponderos/vault

Cloud sync failed (Pro):
- Check internet connection
- Settings → Sync → "Re-sync vault"
- If persists → contact hello@ponderos.com

#Can't find a document I just created

Symptoms:

Document saved but doesn't appear in vault tree
Search returns no results

Solutions:

Refresh vault:
- Click Vault → Right-click → "Refresh"
- Or press Cmd/Ctrl+R
Check folder filters:
- Vault tree might be filtered to a specific project
- Click "All Documents" at the top
Search by filename:
- Press Cmd/Ctrl+K
- Type the exact filename
Check Recently Modified:
- Vault → Sort by "Modified" (descending)
- Your doc should be at the top

#Document formatting looks broken

Symptoms:

Markdown not rendering correctly
Code blocks showing as plain text
Images not displaying

Solutions:

Switch to preview mode:
- Click the "Preview" toggle (top-right)
- Markdown renders correctly in preview
Check Markdown syntax:
- Common errors:
  - Missing blank line before lists
  - Wrong heading syntax (# Heading not #Heading)
  - Unclosed code blocks (need 3 backticks on both ends)
Image paths (local mode):
- Images must be in vault folder
- Use relative paths: ![](./image.png)
- Not: ![](~/Desktop/image.png)

#✅ Task Issues

#Tasks extracted from doc not showing up

Symptoms:

Document has clear action items
Tasks board is empty or missing them

Solutions:

Trigger manual extraction:
- Open AI chat
- Ask: "Extract all action items from [document name]"
Check task board filters:
- Tasks → Make sure no filters are active
- Click "All Projects" + "All Statuses"
Verify doc is saved:
- Unsaved docs won't be indexed
- Press Cmd/Ctrl+S
Wait for indexing (large vaults):
- New docs take ~10 seconds to index
- Check bottom-right corner: "Indexing..." indicator

#Can't drag tasks between columns

Symptoms:

Task won't move when dragged
Drag starts but task snaps back

Solutions:

Check permissions (Pro cloud mode):
- You need write access to the workspace
- Workspace owner can grant in Settings → Team
Browser issue:
- Try refreshing: Cmd/Ctrl+R
- Clear browser cache (if using web version)
Use dropdown instead:
- Click task → Change status dropdown
- Select new status (Backlog/Todo/Done)

#🔄 Sync Issues (Pro Only)

#Changes not syncing across devices

Symptoms:

Edit doc on laptop, changes don't appear on desktop
"Sync conflict" warning

Solutions:

Force sync:
- Settings → Sync → "Sync now"
- Wait for "Last synced: just now"
Check internet connection:
- Sync requires stable connection
- Test: can you access https://ponderos.com?
Resolve conflicts:
- Settings → Sync → "Resolve conflicts"
- Choose which version to keep (local or cloud)
Re-authenticate:
- Settings → Account → "Sign out"
- Sign back in
- Sync should resume

#"Sync failed" error

Common causes:

Supabase outage:
- Check status: https://status.supabase.com
- If down → local changes queued, will sync when service resumes
Auth token expired:
- Sign out + sign back in
- Settings → Account → "Sign out" → "Sign in"
Vault too large:
- Pro allows unlimited docs but individual docs have 50MB limit
- Check Settings → Storage
- Archive or compress large media files

#🚀 Performance Issues

#App is slow or laggy

Symptoms:

Typing has delay
Vault tree takes 5+ seconds to load
AI queries time out

Solutions:

Large vault (1000+ docs):
- Archive old projects: Right-click folder → "Archive"
- Settings → Performance → "Compact database"

Memory usage (desktop app):

# Check if Electron is using >2GB RAM
# macOS: Activity Monitor
# Windows: Task Manager

Close other apps
Restart PonderOS

Slow AI queries:
- Switch model: Settings → AI → "Gemini Flash" (faster)
- Or upgrade: "GPT-4.5 Turbo" (Pro only, better + faster)

Database corruption:

# Backup first!
cp ~/.ponderos/vault.db ~/.ponderos/vault.db.backup

# Then rebuild index
sqlite3 ~/.ponderos/vault.db "REINDEX;"

#Search is slow or missing results

Symptoms:

Search takes 10+ seconds
Recent docs don't appear in results

Solutions:

Rebuild search index:
- Settings → Advanced → "Rebuild search index"
- Takes ~1 minute per 1000 docs
Check search syntax:
- Default: matches any word
- Exact phrase: use quotes "exact phrase"
- Exclude: use minus -word
Use Lumen instead:
- AI chat can do semantic search
- Ask: "Find all docs about [topic]"
- Smarter than keyword search

#🔐 Account & Billing

#Forgot password

Solution:

Login page → "Forgot password?"
Enter email → check inbox for reset link
Link expires in 1 hour

#Can't upgrade to Pro

Symptoms:

Payment form errors
"Card declined" message

Solutions:

Check card details:
- Correct card number, expiry, CVV
- Billing address matches card
Try different payment method:
- We accept Visa, Mastercard, Amex, PayPal
Contact support:
- Email hello@ponderos.com with error message
- We'll manually upgrade and invoice

#Want to cancel Pro subscription

How to cancel:

Settings → Billing → "Cancel subscription"
Takes effect at end of current billing period
Data remains accessible (but cloud sync stops)

Before canceling:

Export your vault: Settings → Export → "Download all docs"
You'll drop to Free tier (25 doc limit)

#🛠️ Advanced Troubleshooting

#Reset PonderOS to factory defaults

⚠️ WARNING: This deletes all local data. Export vault first!

# macOS/Linux
rm -rf ~/.ponderos

# Windows
rmdir /s %APPDATA%\ponderos

Then reinstall PonderOS.

#Enable debug mode

For reporting bugs to support:

Launch with debug flag:

# macOS/Linux
PONDEROS_DEBUG=1 open -a PonderOS

# Windows
set PONDEROS_DEBUG=1 && PonderOS.exe

Reproduce the issue
Logs saved to:
- macOS: ~/Library/Logs/PonderOS/
- Linux: ~/.local/share/PonderOS/logs/
- Windows: %APPDATA%\PonderOS\logs\
Send logs to hello@ponderos.com

#Check system requirements

Minimum:

OS: macOS 12+, Windows 10+, or Ubuntu 20.04+
RAM: 4GB (8GB recommended)
Disk: 2GB free space
Internet: Required for AI queries + cloud sync

Recommended for 1000+ docs:

RAM: 16GB
Disk: SSD (HDD will be slow)

#🆘 Still Stuck?

Get help:

Email: hello@ponderos.com (response within 24h)
Docs: ponderos.com/docs

When reporting a bug, include:

What you were doing (exact steps)
What you expected to happen
What actually happened (screenshot if possible)
Your plan (Free/Pro) and version (Settings → About)
Debug logs (see "Enable debug mode" above)

Most issues are fixable in under 5 minutes. We're here to help! 💙