Troubleshooting

🛠️ Troubleshooting Guide

Having issues with VaultAI? This comprehensive guide covers common problems and their solutions. Most issues can be resolved quickly with the right approach.

🚨 Common Issues & Quick Fixes

🔑 API Key Problems

"API key not working" or "Authentication failed"

Symptoms: Error messages about invalid API key, no responses from AI Solutions:

1. Verify your API key - Copy it fresh from Google AI Studio
2. Check for extra spaces - Paste in a text editor first to remove hidden characters
3. Confirm API quota - Check your usage limits in Google AI Studio
4. Test in browser - Verify the API key works outside Obsidian first

"Rate limit exceeded"

Symptoms: Responses stop working after heavy usage Solutions:

1. Wait a few minutes - Rate limits reset automatically
2. Check quota usage in Google AI Studio dashboard
3. Consider upgrading to paid tier for higher limits
4. Spread usage across longer time periods

💬 Chat Interface Issues

"Chat icon not appearing"

Symptoms: No 🤖 icon in bottom-right corner Solutions:

1. Check plugin status - Ensure VaultAI is enabled in Settings → Community Plugins
2. Restart Obsidian - Close and reopen the app
3. Try keyboard shortcut - Press Ctrl/Cmd+Shift+V to toggle
4. Clear cache - Reload Obsidian with Ctrl/Cmd+R

"Chat opens but won't respond"

Symptoms: Chat interface appears but no AI responses Solutions:

1. Verify API key - Check Settings → VaultAI for correct key
2. Test internet connection - Ensure stable connectivity
3. Check error console - Open Developer Tools (Ctrl+Shift+I) for error messages
4. Try simple prompts - Start with basic questions

📍 Insert Mode Problems

"Insert Mode not inserting content"

Symptoms: AI responds in chat but doesn't insert into document Solutions:

1. Check cursor position - Ensure cursor is active in an editable document
2. Verify Insert Mode - Look for green 📍 button in chat
3. Test in different note - Try in a new, simple note
4. Check document permissions - Ensure note isn't read-only

"Content inserting in wrong location"

Symptoms: AI content appears somewhere unexpected Solutions:

1. Click precisely - Ensure cursor is exactly where you want insertion
2. Avoid text selection - Clear any selected text before using Insert Mode
3. Use plain text notes - Test in markdown files without complex formatting
4. Check for competing plugins - Disable other editing plugins temporarily

⌨️ Keyboard Shortcut Issues

"Shortcuts not working"

Symptoms: Hotkeys don't trigger VaultAI commands Solutions:

1. Check for conflicts - Look for duplicate hotkey assignments
2. Test in different context - Try in various notes and views
3. Reset hotkeys - Remove and reassign the shortcuts
4. Restart after changes - Close and reopen Obsidian

"Command Palette not showing VaultAI"

Symptoms: No VaultAI commands in Ctrl/Cmd+P menu Solutions:

1. Enable plugin - Verify VaultAI is active
2. Configure API key - Commands may hide without valid setup
3. Search specifically - Type "vault" to filter commands
4. Check command names - Look for exact command titles

⚡ Performance Issues

🐌 Slow Response Times

Symptoms: AI takes too long to respond Potential causes & solutions:

Internet connection

• Test your connection speed
• Switch to wired connection if using WiFi
• Try during off-peak hours

API server load

• Google's servers may be busy
• Wait a few minutes and retry
• Consider switching to different Gemini model

Large document context

• Use {{selection}} instead of {{content}} for large notes
• Break large documents into smaller sections
• Clear chat history periodically

💾 Memory & Resource Usage

"Obsidian running slowly with VaultAI"

Solutions:

1. Clear chat history - Delete old conversations in chat interface
2. Restart Obsidian - Fresh start clears memory
3. Limit concurrent usage - Don't run multiple AI requests simultaneously
4. Check other plugins - Disable unnecessary plugins

"Plugin consuming too much memory"

Solutions:

1. Update to latest version - Newer versions often have optimizations
2. Reduce context size - Use shorter prompts and selections
3. Monitor system resources - Close other heavy applications
4. Consider device limits - Older devices may struggle with AI processing

❓ Frequently Asked Questions

General Usage

Q: Can I use VaultAI offline? A: No, VaultAI requires internet connection to communicate with Google's Gemini API.

Q: Is my data secure? A: Yes! Your API key is stored locally and encrypted. Chat history stays in your vault and is never uploaded.

Q: Can I use other AI models? A: Currently VaultAI supports Google Gemini models only. Other models may be added in future updates.

Q: Does VaultAI work on mobile? A: VaultAI is designed for desktop Obsidian. Mobile support depends on Obsidian's mobile plugin capabilities.

Technical Questions

Q: How much does the API cost? A: Google Gemini offers generous free tiers. Most users stay within free limits. Check Google AI pricing for details.

Q: Can I customize the AI model settings? A: Yes! Go to Settings → VaultAI to adjust temperature, max tokens, and model selection.

Q: How do I export my custom prompts? A: Custom prompts are stored in your vault's plugin data. Copy the VaultAI plugin folder to backup/transfer prompts.

Q: Can I use VaultAI in shared vaults? A: Each user needs their own API key. Plugin settings and prompts can be shared via vault sync.

🔍 Error Messages Explained

Common Error Codes

"Invalid API key"

• Meaning: The provided API key is incorrect or expired
• Solution: Generate a new key from Google AI Studio

"Rate limit exceeded"

• Meaning: Too many requests sent too quickly
• Solution: Wait 1-5 minutes before trying again

"Network error"

• Meaning: Connection to Google's servers failed
• Solution: Check internet connection and try again

"Context length exceeded"

• Meaning: Your prompt or content is too long
• Solution: Use shorter selections or split into smaller requests

"Model not available"

• Meaning: Selected AI model is temporarily unavailable
• Solution: Try a different model or wait and retry

🎯 Optimization Tips

For Large Vaults

1. Use targeted selections - Select specific text instead of entire notes
2. Create focused prompts - Be specific about what you want
3. Organize custom prompts - Keep frequently used prompts easily accessible
4. Regular maintenance - Clear old chat history periodically

For Better Performance

1. Keep Obsidian updated - Latest versions have performance improvements
2. Limit active plugins - Disable unused plugins
3. Monitor system resources - Ensure adequate RAM and CPU
4. Use SSD storage - Faster storage improves overall responsiveness

For Optimal AI Results

1. Be specific in prompts - Clear instructions yield better results
2. Provide context - Give AI relevant background information
3. Use examples - Show the format or style you want
4. Iterate and refine - Adjust prompts based on results

🆘 Getting Additional Help

If you're still experiencing issues:

Community Support

• 🐛 Report bugs on GitHub Issues
• 💬 Ask questions in GitHub Discussions
• 🔍 Search existing issues - Your problem might already have a solution

Before Reporting Issues

Please include:

1. Obsidian version and operating system
2. VaultAI version number
3. Steps to reproduce the problem
4. Error messages (exact text or screenshots)
5. Console logs (if applicable)

Debug Information

To help diagnose issues:

1. Open Developer Tools (Ctrl/Cmd+Shift+I)
2. Go to Console tab
3. Look for red error messages
4. Copy error text when reporting issues

---

💡 Remember: Most issues are quick fixes! Don't hesitate to try the simple solutions first.