12 - Troubleshooting & FAQ Guide

12 - Troubleshooting & FAQ Guide

🔧 Common Issues and Solutions
⏱️ Time Estimate: Reference as needed
📋 What You’ll Learn: Solutions to common problems, platform-specific fixes, error resolution

---

Table of Contents

• Installation Issues
• License Activation Problems
• Transcription Failures
• Performance Issues
• Data Recovery
• Audio Recording Issues
• Network & API Issues
• Database Issues
• Platform-Specific Problems

---

Installation Issues

Windows Issues

“Windows protected your PC” warning

Cause: App not digitally signed
Solution:
1. Click "More info"
2. Click "Run anyway"
3. This is safe - Selfoss is open source

Installation fails silently

Check:
✅ Administrator privileges
✅ Antivirus not blocking (whitelist Selfoss)
✅ Windows Defender SmartScreen settings
✅ Sufficient disk space (> 2GB)

Try:
1. Right-click installer → "Run as administrator"
2. Temporarily disable antivirus
3. Re-download installer (may be corrupted)

macOS Issues

“App is damaged” error

Cause: Gatekeeper security
Solution:
xattr -cr /Applications/Selfoss.app

Or:
1. System Preferences → Security & Privacy
2. Click "Open Anyway" for Selfoss

“Cannot verify developer” warning

Solution:
1. Right-click Selfoss.app
2. Select "Open"
3. Click "Open" in dialog
4. This only needed first time

Linux Issues

AppImage won’t run

Make executable:
chmod +x Selfoss.AppImage

Install FUSE (if needed):
Ubuntu/Debian: sudo apt install fuse libfuse2
Fedora: sudo dnf install fuse fuse-libs
Arch: sudo pacman -S fuse2

.deb package conflicts

Force install:
sudo dpkg -i --force-overwrite selfoss.deb
sudo apt-get install -f

---

License Activation Problems

”Invalid license key” error

Causes & Solutions:

❌ Typo in key
   ✅ Copy-paste carefully, check for spaces

❌ Wrong key format
   ✅ Should be: XXXX-XXXX-XXXX-XXXX

❌ Key already used
   ✅ Deactivate on other device first

❌ Expired trial key
   ✅ Purchase full license

“Maximum activations reached”

Solution:

1. Log into customer portal (check email)
2. View active activations
3. Deactivate unused devices
4. Or contact support for reset

“Cannot connect to license server”

Check:

✅ Internet connection active
✅ Firewall not blocking (port 443)
✅ Proxy settings (if corporate network)
✅ Date/time correct (SSL validation)

Try:
1. Disable VPN temporarily
2. Check license.lemonsqueezy.com accessible
3. Restart application

---

Transcription Failures

Empty Transcription Results

For Ollama:

Check:
✅ Ollama running: ollama list
✅ Model downloaded: ollama pull whisper:base
✅ Audio file valid (playback works)
✅ Recording duration > 5 seconds

Fix:
# Restart Ollama
Windows: Right-click tray icon → Restart
Linux: sudo systemctl restart ollama
macOS: Restart from menu bar

# Re-download model
ollama pull whisper:base --force

For OpenAI:

Check:
✅ API key valid
✅ Account has credits
✅ Audio file < 25MB
✅ File format supported (webm/wav/mp3)

Fix:
1. Verify key at platform.openai.com
2. Add payment method if needed
3. Check usage dashboard
4. Try shorter audio file

“Transcription failed” error

Error codes:

401 Unauthorized

Cause: Invalid API key
Fix: Update key in Settings

429 Rate Limit

Cause: Too many requests
Fix: Wait 60 seconds, upgrade tier

500 Server Error

Cause: Provider issues
Fix: Check status page, retry later

Inaccurate Transcription

Improve accuracy:

1. Use better model:
   - Ollama: whisper:small instead of tiny
   - OpenAI: Already uses best

2. Better audio quality:
   - Reduce background noise
   - Speak closer to microphone
   - Use external microphone

3. Try different provider:
   - OpenAI often best for accents
   - Ollama good for privacy

4. Pre-process audio:
   - Remove silence
   - Normalize volume
   - Filter noise (external tool)

---

Performance Issues

Slow Processing

AI processing taking too long:

For Ollama:

Typical times:
- Transcription: 2-5 minutes (1 hour audio)
- Analysis: 30-90 seconds (10-page transcript)

Speed up:
✅ Close other applications
✅ Use smaller model (whisper:base)
✅ Enable GPU acceleration (NVIDIA)
✅ Increase RAM allocation
✅ Upgrade hardware

Check CPU usage:
Windows: Task Manager
macOS: Activity Monitor
Linux: htop

For Cloud Providers:

Typical times:
- OpenAI: 10-30 seconds
- Gemini: 20-40 seconds

If slower:
✅ Check internet speed (> 10 Mbps)
✅ Verify provider status page
✅ Try different time of day
✅ Switch providers temporarily

Application Lag

UI feels sluggish:

Causes:
- Large database (> 1000 transcripts)
- Low RAM (< 8GB)
- Old hardware

Solutions:
1. Optimize database:
   Settings → Advanced → Vacuum Database

2. Clear cache:
   Settings → Advanced → Clear Cache

3. Archive old projects:
   Export → Delete → Free space

4. Close other apps:
   Free up RAM and CPU

5. Upgrade hardware:
   More RAM, SSD, better CPU

Memory Crashes

“Out of memory” errors:

Windows:
1. Task Manager → Details
2. Find selfoss.exe
3. Check memory usage

Solutions:
✅ Close other applications
✅ Process shorter transcripts
✅ Increase virtual memory (pagefile)
✅ Add more RAM (8GB minimum)

---

Data Recovery

Corrupted Database

Symptoms:

- App won't open
- SQLite errors in logs
- Missing/incomplete data

Recovery steps:

1. Backup corrupted database:
   cp selfoss.db selfoss.db.backup

2. Try integrity check:
   sqlite3 selfoss.db "PRAGMA integrity_check;"

3. If errors, try recovery:
   sqlite3 selfoss.db ".recover" | sqlite3 recovered.db

4. If recovery fails, restore from backup:
   - Locate latest backup ZIP
   - Settings → Import Data
   - Select backup file

5. Last resort:
   - Export what you can access
   - Reinstall Selfoss (fresh database)
   - Import saved exports

Lost Transcripts

Transcript disappeared:

Check:
✅ Correct project selected
✅ Search globally (Ctrl+K)
✅ Not filtered out
✅ Database intact

Recover:
1. Check backup files
2. Import from last backup
3. Use "Skip duplicates" mode

Deleted Audio Files

Audio files missing:

If you have backup:
1. Extract backup ZIP
2. Copy audio_recordings/ folder
3. Paste to app data directory
4. Restart Selfoss

If no backup:
- Audio is permanently lost
- Transcripts still accessible
- Can re-record if needed

---

Audio Recording Issues

Microphone Not Detected

Windows:

1. Settings → Privacy → Microphone
2. Enable "Let apps access your microphone"
3. Enable for Selfoss specifically

4. Check default device:
   Control Panel → Sound → Recording
   Right-click microphone → "Set as Default"

5. Test microphone:
   Voice Recorder app

macOS:

1. System Preferences → Security & Privacy
2. Microphone → Enable Selfoss
3. Restart application

4. Check input level:
   System Preferences → Sound → Input
   Adjust input volume

Linux:

# Check available devices
arecord -l

# Test recording
arecord -d 5 test.wav
aplay test.wav

# If no sound, check permissions
sudo usermod -aG audio $USER
# Log out and back in

No Audio in Recording

Solutions:

✅ Check microphone selected (system settings)
✅ Microphone not muted (hardware/software)
✅ Test in other applications
✅ Try different USB port (external mic)
✅ Update audio drivers
✅ Check audio level during recording (green bars)

Recording Stops Unexpectedly

Causes:

- Low disk space (< 100MB)
- System sleep/hibernation
- Memory exhaustion
- Permission revoked

Solutions:
1. Free up disk space
2. Disable sleep during recording
3. Close other applications
4. Re-grant microphone permission
5. Record shorter segments

---

Network & API Issues

Connection Timeout

“Request timed out” error:

Check:
✅ Internet connection active
✅ Can access google.com
✅ Provider status page
✅ Firewall/antivirus not blocking

Fix:
1. Check internet speed (speedtest.net)
2. Disable VPN temporarily
3. Try different network
4. Increase timeout (Settings → Advanced)

SSL/Certificate Errors

“SSL certificate verification failed”:

Causes:
- System date/time incorrect
- Outdated certificates
- Corporate proxy/firewall

Solutions:
1. Correct system date/time
2. Update OS (includes certificates)
3. Disable antivirus SSL scanning
4. Configure proxy settings

Rate Limiting

“Too many requests” (429):

Providers have limits:
- OpenAI Free: 3 requests/minute
- OpenAI Paid: 500/minute
- Gemini Free: 60/minute

Solutions:
✅ Wait 60 seconds
✅ Upgrade provider tier
✅ Process fewer transcripts simultaneously
✅ Use Ollama (no limits)

---

Database Issues

Database Locked

“Database is locked” error:

Causes:
- Another Selfoss instance running
- Previous crash left lock
- Antivirus scanning database

Solutions:
1. Close all Selfoss instances
2. Restart computer
3. Delete .db-shm and .db-wal files
4. Whitelist database in antivirus

Slow Queries

Database operations slow:

Optimize:
1. Settings → Advanced → Vacuum Database
2. Settings → Advanced → Rebuild Indexes
3. Archive old projects
4. Consider SSD if on HDD

---

Platform-Specific Problems

Windows Specific

High DPI issues:

Blurry text/UI:
1. Right-click Selfoss.exe
2. Properties → Compatibility
3. "Change high DPI settings"
4. Override: Application

Windows Defender blocking:

1. Windows Security → Virus & threat protection
2. Manage settings → Add exclusion
3. Add Selfoss folder

macOS Specific

Rosetta on Apple Silicon:

First launch may be slow (translating):
- Wait for "Verifying..." to complete
- Subsequent launches faster

Microphone permission:

Must be granted at:
System Preferences → Security & Privacy → Microphone
App restart required after granting

Linux Specific

Missing dependencies:

# Install required libraries
Ubuntu/Debian:
sudo apt install libwebkit2gtk-4.0-37 libgtk-3-0

Fedora:
sudo dnf install webkit2gtk3 gtk3

Arch:
sudo pacman -S webkit2gtk gtk3

Wayland issues:

If display issues:
GDK_BACKEND=x11 ./Selfoss.AppImage

---

Getting Help

Before Reporting Issues

Collect information:

1. Selfoss version (About → Version)
2. Operating system + version
3. Error messages (exact text)
4. Steps to reproduce
5. Relevant logs (AppData/logs/)

Reporting Bugs

GitHub Issues:

1. Search existing issues first
2. Use issue template
3. Include error logs
4. Describe expected vs actual behavior
5. Add screenshots if UI issue

Community Support

Resources:

• 📚 Documentation: /docs/USER_GUIDES/
• 💬 GitHub Discussions
• 🐛 Issue Tracker
• ✉️ Email Support (premium users)

---

🔧 Most problems have simple solutions - check here first!