Troubleshooting Guide

Solutions to common issues with IfAI.

Installation Issues

macOS: "App is damaged and can't be opened"

This is a macOS security feature.

Solution:

xattr -cr /Applications/IfAI.app

Then try opening the app again.

macOS: "Unidentified developer" warning

Solution:

1. Right-click (or Ctrl-click) the IfAI app
2. Select "Open" from the menu
3. Click "Open" in the confirmation dialog

Windows: "Windows Defender SmartScreen" warning

Solution:

1. Click "More info"
2. Click "Run anyway"
3. Or add IfAI to Windows Defender exclusions

Linux: AppImage won't run

Solution:

chmod +x ifai-*.AppImage
./ifai-*.AppImage

If still not working:

./ifai-*.AppImage --appimage-extract
./squashfs-root/ifai

AI Connection Issues

"Failed to connect to AI provider"

Solutions:

1. Check API key in Settings (Cmd+,)
2. Verify network connection
3. Check provider status page:
   • OpenAI: status.openai.com
   • Anthropic: status.anthropic.com
4. Try switching providers

"Invalid API key"

Solutions:

1. Verify API key in provider dashboard
2. Check for extra spaces when pasting
3. Ensure key has sufficient credits/quota
4. Regenerate key if needed

"Rate limit exceeded"

Solutions:

1. Wait a few minutes and try again
2. Upgrade your API plan
3. Use a different provider
4. Switch to local model (Ollama)

AI responses are slow

Solutions:

1. Reduce context (fewer files)
2. Switch to faster model (e.g., GPT-3.5 instead of GPT-4)
3. Use local model for instant responses
4. Check network speed

Performance Issues

IfAI is slow or lagging

Solutions:

1. Close unused files
2. Reduce AI context size
3. Disable unused extensions
4. Restart IfAI
5. Check system resources (Activity Monitor / Task Manager)

High memory usage

Solutions:

1. Close unused files
2. Clear chat history
3. Reduce symbol indexing scope
4. Restart IfAI periodically

Editor freezes when AI is thinking

This is normal for complex operations. AI responses stream in real-time, and large files may take longer to process.

Editor Issues

Code highlighting not working

Solutions:

1. Check file extension matches language
2. Try "Reopen with" and select correct language
3. Check if language is supported

Auto-completion not working

Solutions:

1. Check file is saved
2. Verify language server is running
3. Try restarting IfAI
4. Check Settings > Editor > Enable Auto-completion

Go to Definition not working

Solutions:

1. Wait for indexing to complete (check status bar)
2. Ensure file is saved
3. Check if language supports navigation
4. Try rebuilding symbol index: Cmd+Shift+P > "Rebuild Index"

File & Project Issues

Files not appearing in file tree

Solutions:

1. Check if folder is excluded in Settings
2. Click "Refresh" in file tree header
3. Reopen project folder
4. Check file permissions

Can't save file

Solutions:

1. Check file permissions
2. Ensure disk has space
3. Check if file is locked by another program
4. Try "Save As" to different location

Git changes not showing

Solutions:

1. Check if repository is initialized
2. Click "Refresh" in file tree
3. Check Settings > Git > Enable Git Integration
4. Verify git is installed and in PATH

Local LLM Issues

Ollama not detected

Solutions:

1. Verify Ollama is installed: ollama --version
2. Check Ollama is running: ollama list
3. Restart IfAI after starting Ollama
4. Check IfAI Settings > AI Provider > Ollama

Local model is very slow

Solutions:

1. Check if model is loaded: ollama ps
2. Use smaller model (e.g., qwen2.5-coder:3b)
3. Ensure sufficient RAM (8GB+ for 7B models)
4. Close other applications

Out of memory errors

Solutions:

1. Use smaller quantization model
2. Reduce context window size
3. Close other applications
4. Switch to cloud provider

Crash Recovery

IfAI crashed unexpectedly

Solutions:

1. Check for crash logs:
   • macOS: ~/Library/Logs/IfAI/
   • Windows: %APPDATA%\IfAI\logs\
   • Linux: ~/.config/IfAI/logs/
2. Restart IfAI
3. File is usually auto-saved

Recovering unsaved work

IfAI auto-saves your work. To recover:

1. Open the file you were working on
2. Check for .backup files in project directory
3. Use system file history (Time Machine, etc.)

Getting Help

Still having issues?

1. Check Documentation: docs
2. Search Issues: GitHub Issues
3. Ask Community: GitHub Discussions
4. Report Bug: Create Issue

When reporting issues, please include:

• IfAI version
• Operating system
• Steps to reproduce
• Error messages or logs