Troubleshooting

Common issues and how to resolve them.

AI & Models

Model download fails or is slow

AI models are large files (4-8 GB) downloaded from Hugging Face. If downloads fail:

  • Check your internet connection
  • Ensure you have enough disk space (at least 10 GB free recommended)
  • Try again later - Hugging Face may have temporary issues
  • If on a corporate network, check if Hugging Face is blocked

Smart Search responses are slow

Local AI performance depends on your hardware:

  • More RAM = better performance. 16 GB is recommended, 32 GB is ideal
  • Close other memory-intensive applications
  • Try a smaller model (e.g., 7B instead of 12B parameters)
  • The first response after launching may be slower while the model loads

Smart Search gives inaccurate or irrelevant responses

Historicle uses retrieval-augmented generation (RAG) to ground responses in your actual entries:

  • Make sure you've generated embeddings (Settings > Journal Search > Generate Embeddings)
  • Use @mentions and #hashtags in your entries to improve retrieval
  • Be specific in your questions to help the AI find relevant entries
  • Larger models generally produce better results but are slower

Semantic search returns no results

  • Verify the embedding model is downloaded (Settings > Journal Search)
  • Click "Generate Embeddings" to index your entries
  • Wait for embedding generation to complete before searching
  • Check that you have entries in your journal

Face recognition isn't working

  • Ensure you've trained faces with at least 3-5 clear photos per person
  • Use photos with good lighting and clear face visibility
  • The face recognition model needs to be downloaded first
  • Very small faces in photos may not be detected

Audio transcription fails

  • Ensure the Whisper model is downloaded (Settings > Speech Recognition)
  • Check that your audio recording isn't corrupted
  • Very long recordings may take a while to process
  • Clear audio with minimal background noise transcribes best

Performance

App is slow or unresponsive

  • Restart Historicle
  • Check Activity Monitor for high CPU/memory usage
  • If you have many entries (>10,000), some operations may take longer
  • Disable face recognition processing if not needed

High memory usage

AI models require significant RAM. Historicle tries to manage memory efficiently, but:

  • The LLM model stays in memory for faster responses
  • You can unload the model by closing the Smart Search view when not in use
  • Smaller models use less memory
  • 16+ GB RAM is recommended for comfortable usage

App takes a long time to start

  • First launch after update may be slower (database migrations)
  • Large photo libraries take time to index
  • Try disabling auto-load of AI models in Settings

Data & Sync

Entries aren't saving

  • Check that you have disk space available
  • Look for error messages in the status bar
  • Try restarting the app
  • Check file permissions on ~/Library/Application Support/ai.historicle.app/

Backup fails

  • Ensure you have write permission to the backup location
  • Check available disk space
  • Try a different backup location
  • For cloud sync, verify your cloud storage is connected and has space

Day One import is incomplete

  • Ensure you're exporting from Day One in JSON format
  • Very large exports may take a while to process
  • Check that photos are included in the export
  • Some Day One formatting may not transfer perfectly

Photos aren't displaying

  • Check that the original photos still exist at their paths
  • Photos are stored in the app's data directory - don't move or delete them
  • Try re-adding the photo to the entry

Local Server & MCP

Can't connect from mobile device

  • Ensure both devices are on the same network
  • Check that the Local Server is running (Settings > Server)
  • Verify the port isn't blocked by firewall
  • Use the QR code to ensure you have the correct address
  • Try using the local IP address instead of hostname

MCP connection not working

See our detailed MCP Setup Guide for step-by-step instructions and troubleshooting.

API key not working

  • Verify you're using the correct API key
  • Check that the key has the required scopes for your operation
  • Ensure the Local Server is running
  • API keys are case-sensitive - copy them exactly

Installation & Updates

App won't launch

  • Ensure you're running macOS 13.0 (Ventura) or later
  • Verify you have an Apple Silicon Mac (M1, M2, M3, or M4)
  • Try right-click > Open if you see a security warning
  • Reinstall from the App Store

Can't restore Pro purchase

  • Sign into the same Apple ID used for the original purchase
  • Open the App Store and go to Account > Purchased
  • Try "Restore Purchases" in Historicle Settings
  • Contact Apple Support if the purchase doesn't appear

Reset & Recovery

Reset to factory settings

If all else fails, you can completely reset Historicle:

  1. Export a backup of your data first (Settings > Backup)
  2. Quit Historicle
  3. Delete ~/Library/Application Support/ai.historicle.app/
  4. Restart Historicle
  5. Restore from your backup if needed

Warning: This deletes all your local data. Backups stored on your sync drive (iCloud, Google Drive, Dropbox, etc.) will persist unless you manually delete them separately.

Recover from corrupted database

If you see database errors:

  1. Quit Historicle
  2. Locate the database at ~/Library/Application Support/ai.historicle.app/db/
  3. Try restoring from a recent backup
  4. Contact support if you need help recovering data

Still Need Help?

If you've tried these solutions and still have issues, contact our support team. Please include:

  • Your macOS version
  • Your Mac model (e.g., MacBook Pro M3)
  • Steps to reproduce the issue
  • Any error messages you see