Troubleshooting

Start with the smallest check that matches the symptom. The desktop app’s status indicator should be green, and this request should return JSON:

curl http://127.0.0.1:7242/status

“MemSearch is damaged and can’t be opened”

Current releases are not notarized. If you downloaded MemSearch from the project’s Releases page, clear the quarantine attribute once:

xattr -cr /Applications/MemSearch.app

Use the real path if the app is not under /Applications. Then open it normally.

Photos access denied

1. Open System Settings → Privacy & Security → Photos.
2. Enable access for MemSearch.
3. Quit and reopen MemSearch if the permission list does not update.
4. Select Index Photos again.

The current backend accepts full authorized status. Limited or denied access can produce a 403 response.

If people are missing but image indexing works, name the people in Photos and use Refresh People. Confirm that the configured library contains:

database/Photos.sqlite

Invalid, expired, or rate-limited Gemini key

Search maps common Gemini failures to local 503 responses:

Saving a key in the desktop Status page writes it to Electron Store and restarts the backend. The onboarding field only checks that the value is non-empty, so a bad key may surface later during the first index or search request.

Backend disconnected or reconnecting

The desktop app health-checks http://127.0.0.1:7242/status. During a deliberate restart it may show Reconnecting to backend… before it displays a hard error.

1. Wait through first-run dependency setup; the first launch allows up to 120 seconds.
2. Select Restart Backend from the Status error panel.
3. Confirm the log path shown below.
4. Confirm nothing else owns port 7242.
5. Verify that the packaged app contains its backend resources, or that source development has backend beside electron.

An unexpected backend exit after reaching ready state triggers one automatic restart after two seconds.

First-run dependency setup fails

The desktop app searches these uv locations:

app bundle resources/bin/uv
~/.local/bin/uv
~/.cargo/bin/uv
/usr/local/bin/uv
/opt/homebrew/bin/uv

If none exists, it runs the official installer. Install manually when that step fails:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then reopen MemSearch. For a source checkout, verify independently:

cd backend
uv sync
uv run memsearch status

The packaged app puts its writable Python environment at:

~/Library/Application Support/MemSearch/venv

If that environment is incomplete, quit the app, move the directory aside as described under reset procedures, and relaunch.

Port 7242 is already in use

Inspect the listener:

lsof -nP -iTCP:7242 -sTCP:LISTEN

Do not run a source memsearch serve process at the same time as the Electron desktop backend. Current Electron startup evicts a process already answering on port 7242 before it launches the managed server.

For a standalone source server, choose another loopback port:

MEMSEARCH_PORT=7243 uv run memsearch serve

Update the Raycast Backend URL accordingly. The current Electron renderer is hard-coded to port 7242, so changing the backend port is not a desktop-app workaround.

Indexing reports failures or skips everything

Check these conditions:

• The folder exists and the current process can read it.
• Files use a supported extension.
• Files are not empty or above MEMSEARCH_MAX_FILE_SIZE_MB.
• A path component is not hidden, node_modules, .git, __pycache__, .DS_Store, or Thumbs.db under the default exclusions.
• The file is actually newer than the stored entry; unchanged items are expected to be skipped.
• PDF or image files are not corrupt.
• Gemini is reachable and the key has quota.
• ChromaDB and thumbnail directories are writable.

File status retains up to 100 detailed errors. Photos status exposes the first embedding failure and the latest result briefly after a run.

Photos indexing appears stuck

The current asset string identifies phases such as scanning, checking existing photos, downloading, and embedding. An iCloud asset request can block while PhotoKit downloads the original.

• Confirm network access and Photos sync.
• Wait for the current download.
• Use Stop Indexing; the desktop restarts the backend because PhotoKit cancellation is not always prompt.
• Retry. Already written assets remain and unchanged assets are skipped.

Search returns no results

• Check that Status has items in the chosen modality.
• Select All Types.
• Try a shorter, concrete query.
• Remove incorrect @person filters.
• Refresh people after renaming faces in Photos.
• Re-index the source after changes.
• Check for a Gemini error; every query must be embedded before local comparison.

Raycast cannot connect

Use http://localhost:7242 or http://127.0.0.1:7242 as the extension’s Backend URL and confirm /status with curl. Start the desktop app or uv run memsearch serve. See the full Raycast troubleshooting guide.

Logs

The desktop-managed backend appends logs here:

~/Library/Application Support/MemSearch/logs/backend.log

Watch recent lines while reproducing a problem:

tail -f "$HOME/Library/Application Support/MemSearch/logs/backend.log"

The file can contain local paths, filenames, dates, and service error text. Review it before sharing.

Source runs print directly to the terminal unless you redirect them.

Reset procedures

Clear search data only

Use the confirmed desktop action, or:

cd backend
uv run memsearch clear

This preserves configuration, the API key, logs, and source files.

Reset backend UI-managed settings

Quit MemSearch, preserve a backup, and relaunch:

mv "$HOME/Library/Application Support/MacMemorySearch/config.json" \
  "$HOME/Library/Application Support/MacMemorySearch/config.json.backup"

Environment variables still override defaults after this reset.

Rebuild the desktop Python environment

Quit MemSearch and move the environment aside:

mv "$HOME/Library/Application Support/MemSearch/venv" \
  "$HOME/Library/Application Support/MemSearch/venv.backup"

The next launch recreates it and may take up to two minutes.

Reset onboarding and the stored key

Quit MemSearch, then move the Electron Store file aside:

mv "$HOME/Library/Application Support/MemSearch/config.json" \
  "$HOME/Library/Application Support/MemSearch/config.json.backup"

On the next launch, onboarding runs again. This also removes the active Electron settings file containing the plaintext Gemini key; the .backup still contains that sensitive value until you secure or remove it.

Full index-directory reset

If ChromaDB is damaged and the normal clear command cannot run, quit every Memsearch process and move the local index and thumbnail directories aside:

mv "$HOME/Library/Application Support/MacMemorySearch/chroma" \
  "$HOME/Library/Application Support/MacMemorySearch/chroma.backup"
mv "$HOME/Library/Application Support/MacMemorySearch/thumbnails" \
  "$HOME/Library/Application Support/MacMemorySearch/thumbnails.backup"

Relaunch and re-index. Source files and Photos assets are unaffected.