Troubleshooting & Diagnostics

This guide provides step-by-step diagnostic procedures and solutions for common issues encountered when using Garage.

Quick Diagnostic Matrix

1. PostgreSQL Service Issues

Port 14824 Unavailable

Symptom: GarageApp indicates database error or CLI fails with: psycopg2.OperationalError: could not connect to server: Connection refused

Solution:

1. Check if another instance or zombie process is using port 14824:

   lsof -i :14824
   

2. If a stale postgres process exists, stop it:

   kill -TERM <PID>
   

3. In GarageApp, click the menu bar icon and choose Restart Database.

Orphaned postmaster.pid File

Symptom: PostgreSQL log reports lock file "postmaster.pid" already exists and server does not start after a macOS crash or forced shutdown.

Solution: Verify no postgres processes are active, then remove the stale lock file:

rm -f ~/Library/Application\ Support/GarageApp/pgdata/postmaster.pid

Multithreaded Startup Error

Symptom: Log contains FATAL: postmaster became multithreaded during startup.

Cause: Custom macOS locale settings can spawn auxiliary threads during runtime initialization before postgres fork safety validation.

Solution: Ensure LC_ALL=C is exported in the environment before launching postgres (handled automatically by GarageApp).

Starting over with an empty database

Database → Reset Database… deletes everything Garage built from your files and nothing else:

• Deleted: the search index (documents, chunks and embeddings), facts, the conversation memory imported from Messages and Mail, and the source, model, author and ingest records.
• Kept: your original files, downloaded model files, logs, garage.json and the Keychain password.

Garage stops its services, deletes the database folder and relaunches into the setup assistant. Its first page creates the new database and registers the sources in garage.json again; the next pages let you add sources, choose embedding models and connect your agents. Skip setup finishes the reset without the assistant and leaves you on the Status page to set things up yourself. Either way, run ingest afterwards to rebuild the index.

To keep a way back, press Back Up First… in the confirmation sheet before resetting. It saves the same dump as Back Up…, and Restore… on the Database page loads it into the new database.

2. macOS Permissions (TCC) & Protected Files

authorization denied on chat.db or ~/Library/Mail

Symptom: Ingestion log reports permission failure reading SMS / iMessage or Apple Mail databases.

sqlite3: unable to open database ~/Library/Messages/chat.db: authorization denied

Solution:

1. Open System Settings → Privacy & Security → Full Disk Access.
2. Click the lock/add icon and ensure both GarageApp and your terminal emulator (e.g. Terminal, iTerm2, or Ghostty) are added with toggle enabled.
3. If permissions were changed while the app was running, quit and re-launch GarageApp.

3. Embedding Models & Providers

Ollama / LM Studio Connection Refused

Symptom: garage backfill fails with ConnectionRefusedError: [Errno 61] Connection refused.

Solution:

• Ollama: Verify Ollama is running (ollama list). Start Ollama via ollama serve or open the Ollama desktop app.
• LM Studio: Open LM Studio, select the Developer tab, and click Start Server on port 1234.

Vector Dimension Mismatch

Symptom: PostgreSQL error different vector dimensions during backfill.

Cause: Each embedding table emb_<slug> is strictly typed to its model’s vector dimensions (e.g., 1024 for bge-m3, 768 for nomic-embed-text).

Solution: Inspect your registered model settings:

garage list-models

If registered incorrectly, drop the model (this discards its vectors) and re-register it with the right width, then backfill:

garage drop-model <model-name> --yes
garage register-model <model-name> --provider ollama --dims <correct-dims>
garage backfill --model <model-name>

4. Model Context Protocol (MCP)

HTTP 421 Misdirected Request

Symptom: Browser or custom client receives 421 Misdirected Request when connecting to http://127.0.0.1:8787/mcp.

Cause: On a loopback bind the MCP HTTP server checks the Host header (DNS rebinding protection). Requests must send 127.0.0.1:8787 or localhost:8787.

Solution: Ensure your client sends Host: 127.0.0.1:8787. If accessing from a web application, specify --allow-origin <origin>. When serving remotely (--allow-remote), pass each name clients will use with --allow-host <host:port> (or <host>:*); with no --allow-host the Host check is switched off and a warning is logged.

Claude Desktop Not Detecting Tools

Symptom: Claude Desktop starts, but the rag_search or rag_get_document tools are missing.

Solution:

1. Check ~/Library/Application Support/Claude/claude_desktop_config.json.
2. Confirm the entry for garage exists and has the correct path to garage-mcp.
3. Re-install using:

   garage mcp-install --target claude-desktop
   

4. Completely quit Claude Desktop (Cmd+Q) and reopen it.

5. Cloud Placeholders & Online Files

Unintended Downloads of Online-Only Files

Symptom: Ingestion takes a long time and starts downloading large quantities of cloud files from Dropbox or iCloud Drive.

Solution: Garage meters cloud stub materialization. In ~/.garage.json, adjust placeholder materialization settings:

{
  "placeholders": {
    "materialize": false,
    "limit": 50,
    "max_bytes": 104857600
  }
}

Setting "materialize": false ensures online-only placeholders are indexed as metadata stubs without downloading their contents.

6. Inspecting Diagnostic Logs

When diagnosing issues, check the relevant logs:

• PostgreSQL Database Logs: ~/Library/Group Containers/DWVXMLB45Y.group.me.rickmark.garage-rag/Library/Application Support/GarageApp/logs/postgres.log
• Ingestion & CLI Logs: ~/Library/Group Containers/DWVXMLB45Y.group.me.rickmark.garage-rag/Library/Application Support/GarageApp/logs/ingest.log
• MCP Server Logs: ~/Library/Group Containers/DWVXMLB45Y.group.me.rickmark.garage-rag/Library/Application Support/GarageApp/logs/mcp.log

With the direct-download (Developer ID) build, ~/Library/Application Support/GarageApp is a shortcut to the same folder, so ~/Library/Application Support/GarageApp/logs/ works too.