Troubleshooting.md

Troubleshooting

Common issues and solutions.

🔧 Installation Issues

python: command not found

Solution: Use python3 instead of python

pip: command not found

Solution:

python3 -m ensurepip --upgrade
# Or on Ubuntu:
sudo apt install python3-pip

Virtual environment not activating

Solution: Check you're using the right command:

• macOS/Linux: source venv/bin/activate
• Windows CMD: venv\Scripts\activate
• Windows PowerShell: .\venv\Scripts\Activate.ps1

🐛 Runtime Issues

Analysis returns wrong context

Check:

• HTML structure (use semantic elements)
• Content actually matches expected type
• Try forcing context: data-wisp-force="narrative"

CSS not applying

Check:

• CSS file is loaded (check Network tab)
• No syntax errors in browser console
• Try inline styles first to debug

Fetch fails with SSL error

Solution: Update certificates

# macOS
brew install ca-certificates

# Ubuntu
sudo apt update && sudo apt install ca-certificates

🌐 Browser Issues

Styles not loading on GitHub Pages

Solution:

• Check browser console for 404 errors
• Ensure using HTTPS URLs
• Clear browser cache

Dark mode not working

Solution: Check system preferences:

• macOS: System Preferences → Appearance
• Windows: Settings → Personalization → Colors
• Must be set to "Dark"

Animations not disabled

Solution: Check accessibility settings:

• macOS: System Preferences → Accessibility → Display
• Look for "Reduce motion" option

📝 CLI Issues

wisp-fetch: command not found

Solutions:

1. Use ./wisp-fetch from wisp directory
2. Or use full path: ~/wisp/wisp-fetch
3. Or create symlink: sudo ln -s ~/wisp/wisp-fetch /usr/local/bin/

Permission denied

Solution: Make executable:

chmod +x wisp-fetch

🔄 Git Issues

Push rejected

Solution: Pull first:

git pull origin main --no-rebase
git push origin main

Merge conflicts

Solution:

git status  # See conflicted files
# Edit files to resolve
git add .
git commit -m "merge: resolve conflicts"

📊 Performance Issues

Analysis is slow

Check:

• HTML file size (should be <1MB for best performance)
• Deeply nested DOM (flatten if possible)
• Running on appropriate hardware

Out of memory

Solution: Process in chunks:

# Instead of loading entire file
with open('large.html') as f:
    content = f.read()  # Don't do this for huge files

# Stream or chunk instead

🆘 Still Need Help?

• Check GitHub Issues
• Review API Reference
• Read Architecture guide

---