Troubleshooting

Common issues and how to resolve them.

Last updated: April 2026

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 shows a note at the top of the screen describing what to expect on your particular machine — whether it can use your graphics card, and roughly how quick answers should feel. Everything else in Historicle performs the same regardless.

On Windows specifically:

  • Historicle uses your graphics card through Vulkan when one is available, which is meaningfully faster than working on the processor alone
  • The first search after installing or updating takes about ten seconds longer while graphics shaders are prepared. This happens once — later searches are quicker
  • Integrated graphics (Intel Iris, Intel Arc, AMD Radeon Graphics) help, but a dedicated graphics card is considerably faster

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

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

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 (Mac)

  • 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

App won't launch (Windows)

  • Ensure you're running 64-bit Windows 10 or 11
  • Reinstall from the Microsoft Store

If Windows shows "vulkan-1.dll was not found", or an error code of 0xc0000135, your graphics driver is missing or too old. Historicle uses Vulkan for Smart Search, and Windows will not start the app without it. Updating your graphics driver installs it:

This affects a small number of machines — most commonly virtual machines, or a fresh Windows install that has not had a graphics driver update yet. Restart after installing the driver.

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