Troubleshooting

Connection Issues

SafeRag shows "Ollama not connected"

Symptoms: Red indicator in status bar, unable to chat, models not loading.

Solutions:

Connection times out

Symptoms: SafeRag hangs when trying to connect, eventually shows timeout error.

Solutions:

• Ensure no firewall is blocking localhost connections
• Quit any separate Ollama installation that might conflict
• Restart SafeRag or your Mac

Model Issues

Model download fails

Symptoms: Download starts but never completes, or shows error.

Solutions:

• Check internet connection - Model downloads require internet access
• Check disk space - Ensure you have enough free space for the model
• Try smaller model - If a large model fails, try downloading a smaller one first
• Download via Terminal - Run ollama pull modelname in Terminal for more detailed error messages

Model runs slowly

Symptoms: Responses take a long time, typing indicator shows for extended periods.

Solutions:

• Use a smaller model - Smaller models (3B, 7B) are faster than larger ones
• Close other applications - Free up RAM for the AI model
• Check Activity Monitor - Ensure nothing else is consuming CPU
• Consider your hardware - More RAM and newer Apple Silicon chips provide better performance

Model produces poor quality responses

Solutions:

• Try a different model - Different models excel at different tasks
• Be more specific - Provide clearer, more detailed prompts
• Use a larger model - Larger models generally produce better quality responses

Chat Issues

Messages not sending

Symptoms: Pressing Enter does nothing, message stays in input field.

Solutions:

• Check Ollama connection status (green indicator)
• Ensure you have at least one model installed
• Try creating a new session
• Restart SafeRag

Response cuts off mid-sentence

Symptoms: AI response stops abruptly without completing.

Solutions:

• Context length limit - Very long conversations may hit the model's context limit. Start a new session.
• Memory pressure - Close other apps to free up RAM
• Ask for continuation - Type "continue" or "please finish your response"

Chat history missing

Symptoms: Previous conversations not showing.

Solutions:

• Check if you're logged into the correct account (Multi-User mode)
• Sessions may have been deleted by retention policy
• Restore from backup if available

Document Issues

Document upload fails

Symptoms: Error when trying to upload, document doesn't appear in list.

Solutions:

• Check file type - Only PDF, TXT, MD, and images are supported
• Check file size - Very large files may timeout
• Check document limit - Free tier limited to 5 documents
• PDF issues - Scanned PDFs without text layers won't work well

RAG not finding relevant content

Symptoms: AI doesn't reference your documents even when relevant.

Solutions:

• Use RAG mode - Ensure you're in a RAG session, not General mode
• Install embedding model - Download an embedding model like nomic-embed-text
• Be specific - Use keywords that appear in your documents
• Re-upload documents - Delete and re-upload to regenerate embeddings

Account Issues

Forgot password

Solutions:

• Use recovery codes - Enter one of your 6 recovery codes to reset password
• Contact admin - In Multi-User mode, an admin can reset your password

Can't login

Solutions:

• Check caps lock is off
• Ensure you're using the correct username
• Try password reset with recovery codes

Performance Issues

SafeRag is slow or unresponsive

Solutions:

• Restart the app - Quit and reopen SafeRag
• Check Activity Monitor - Look for high CPU or memory usage
• Free up RAM - Close unnecessary applications
• Restart your Mac - Clears system caches and frees resources

High disk usage

Solutions:

• Remove unused models - Each model uses several GB
• Delete old sessions - Or enable retention policy
• Clear old backups - Reduce number of backups kept

Installation Issues

"SafeRag can't be opened because Apple cannot check it for malicious software"

Solution:

1. Go to System Settings > Privacy & Security
2. Scroll down to find the message about SafeRag
3. Click Open Anyway

"SafeRag is damaged and can't be opened"

Solutions:

• Re-download SafeRag from the official website
• Clear extended attributes: xattr -cr /Applications/SafeRag.app

Resetting SafeRag

As a last resort, you can reset SafeRag to its initial state:

~/Library/Application Support/SafeRag

Getting More Help

If your issue isn't covered here:

When Contacting Support

Please include:

• macOS version (e.g., macOS 14.5)
• SafeRag version (found in SafeRag > About SafeRag)
• Mac model and chip (e.g., MacBook Pro M3)
• Steps to reproduce the issue
• Any error messages you see

Frequently Asked Questions

How much disk space do AI models need?

It varies by model. Typical sizes:

• 3B models: ~2 GB
• 7B models: ~4 GB
• 13B models: ~8 GB
• 70B models: ~40 GB

Can I use SafeRag offline?

Yes! After initial setup and model download, SafeRag works completely offline. The only features requiring internet are downloading new models and optional crash reporting.

Does SafeRag work on Intel Macs?

No, SafeRag requires an Apple Silicon Mac (M1, M2, M3, or M4). Intel Macs are not supported.

How do I update SafeRag?

Download the latest version from our website and replace the app in your Applications folder. Your data is preserved in a separate location.

Why is my trial expired?

The 24-hour trial starts when you first launch SafeRag. After it expires, you can continue using free features or enter a license key for Pro.