Troubleshooting

Common issues and solutions for PersistenceAI.

Installation Issues

Install Script Fails

Problem: Install script fails to download or execute. Solutions:

Check your internet connection
Verify the install URL is correct:

- Linux/macOS: https://persistence-ai.github.io/Landing/install.sh - Windows: https://persistence-ai.github.io/Landing/install.ps1

Try downloading the binary directly from Releases

Binary Not Found After Installation

Problem: persistenceai command not found. Solutions:

Verify the binary was installed:

- Windows: %USERPROFILE%\.persistenceai\bin\persistenceai.exe - Linux/macOS: ~/.persistenceai/bin/persistenceai

Check your PATH environment variable includes the install directory
Restart your terminal after installation

Configuration Issues

Config File Not Found

Problem: PersistenceAI can't find your config file. Solutions:

Create the config directory:

- Windows: %USERPROFILE%\.config\pai\ - Linux/macOS: ~/.config/pai/

Create pai.json with basic configuration:

{
     "keybinds": {},
     "providers": {}
   }

Keybinds Not Working

Problem: Keyboard shortcuts don't work. Solutions:

Check your keybind configuration in pai.json
Verify the leader key is set correctly (default: Ctrl+X)
Ensure no other application is capturing the shortcuts
Try resetting keybinds to defaults

Provider Issues

API Key Not Working

Problem: Provider authentication fails. Solutions:

Verify your API key is correct
Check API key hasn't expired
Ensure you have sufficient credits/quota
Try reconnecting: /connect

Ollama Connection Failed

Problem: Can't connect to Ollama. Solutions:

Verify Ollama is running:

ollama list

Check Ollama base URL (default: http://localhost:11434)
Ensure firewall isn't blocking the connection
Try restarting Ollama service

Performance Issues

Slow Response Times

Problem: PersistenceAI responds slowly. Solutions:

Check your internet connection (for cloud providers)
Try a faster model (smaller models are faster)
For Ollama: Ensure GPU acceleration is enabled
Check system resources (CPU, RAM, GPU)

High Memory Usage

Problem: PersistenceAI uses too much memory. Solutions:

Use smaller models
Close unused sessions
Restart PersistenceAI periodically
Check for memory leaks in your terminal

Feature Issues

@ File Search Not Working

Problem: @ shortcut doesn't show file suggestions. Solutions:

Ensure you're in a project directory (not empty)
Run /init to initialize the project
Check file permissions
Verify workspace is enabled (Ctrl+B)

Editor Not Opening

Problem: Editor pane doesn't open. Solutions:

Press Ctrl+E to toggle editor
Check editor configuration
Verify file permissions
Try opening external editor: E

Commands Not Working

Problem: Commands like /undo don't work. Solutions:

Ensure you're in an active session
Check command syntax (must start with /)
Verify the command exists: /commands
Check session state (some commands require specific states)

Terminal Compatibility

Windows PowerShell Issues

Problem: TUI doesn't render correctly in PowerShell. Solutions:

Use Windows Terminal instead of PowerShell 5.1
Update to PowerShell 7+
Use a modern terminal emulator (WezTerm, Alacritty)

Terminal Not Supported

Problem: Terminal compatibility errors. Solutions:

Use a modern terminal emulator:

- WezTerm (cross-platform) - Alacritty (cross-platform) - Windows Terminal (Windows) - iTerm2 (macOS)

Check terminal supports:

- True color - Unicode - Mouse events

Getting Help

If you're still experiencing issues:

Check Documentation: Review the full documentation
Search Issues: Check GitHub Issues
Report Bug: Open a new issue
Community: Join our Discord or community forums

Common Error Messages

"Provider not configured"

Solution: Run /connect to configure a provider.

"Session not found"

Solution: Create a new session with /new or list sessions with /session.

"Model not available"

Solution: Check model name is correct, or select from /models.

"Permission denied"

Solution: Check file permissions and ensure PersistenceAI has access.

For more help, see: