Troubleshooting

Keychain prompts on first launch

When you first open Golden Retriever after installation, macOS will show three keychain access prompts (one for each secure storage item). Click “Always Allow” on each. This is a one-time setup — you won’t see these again.

If you accidentally clicked “Deny”, go to Keychain Access.app, find the Golden Retriever entries, and delete them. Then relaunch the app.

”Rate limit exceeded” error

This means you’ve hit Google’s API rate limit. The free Gemini API tier has usage caps:

Embedding: 1,500 requests per minute
Search/Ask AI: 15 requests per minute

What to do: Wait a minute and try again. During large folder indexing, the app automatically throttles to stay within limits.

Qdrant won’t start

Golden Retriever bundles Qdrant (the vector search engine) inside the app. If it fails to start:

Check Settings → Diagnostics for error details
Make sure no other Qdrant instance is running on port 6334
Try quitting and relaunching the app

Files not appearing after indexing

Folders are added and managed in the Library tab — it’s the single place for content management (Settings is preferences only). If you added a folder but files don’t show up in search:

Check the Library tab — look for files with error icons
Make sure the files are in a supported format
Check that the folder has read permissions (right-click → Get Info in Finder)
Try running the pipeline again from the Library tab

See The Library browser for a full tour, including how to retry failed files.

Search returns no results

Make sure indexing has completed (check the Library tab for progress)
Try broader search terms — semantic search finds meaning, not exact keywords
Check that Qdrant is running (Settings → Diagnostics)

Migrating from the old app (0.9.x)

If you ran the previous beta, the rebuilt app offers to bring your library across on first launch. A few things to know:

The import reads your existing data in place — the old app doesn’t need to be installed or running.
Everything copied is verified, and your original data is never modified.
If the import is interrupted, it can be resumed — you won’t lose progress.

See the migration guide for what carries over and what doesn’t.

Updates aren’t arriving

During the beta, the app updates itself from the gr2-beta update channel and checks automatically. To check manually, choose Check for Updates… from the app’s menu bar. Every update is signature-verified before it installs — the app refuses anything that isn’t signed by us. See Auto-updates for details.

Media uploads seem smaller than the original files

That’s expected. By default, photos, videos, and audio are compressed before upload to make ingestion faster and cheaper, with no measurable loss in AI understanding (a 19 MB video clip becomes roughly 6 MB). If you prefer full-quality uploads, you can turn this off in Settings.