Health Check and Troubleshooting

How to diagnose infrastructure issues, check connector health, and recover from common problems using Coppermind's built-in diagnostic tools.

First, Try This (fixes most "weird" behavior)#

Before anything else, two 30-second fixes clear the most common Claude Desktop quirks. Try them first -- they solve the majority of "it's acting weird" reports.

A tool is missing, acting weird, or says "failed to fetch"? Quit and reopen Claude Desktop.#

Claude Desktop caches MCP tool definitions aggressively. When a tool gets updated, disappears from the list, throws a "failed to fetch" error, or just behaves oddly, the cache is almost always the cause. A full restart clears it.

1. Fully quit Claude Desktop (Cmd+Q on Mac, or right-click the taskbar icon > Quit on Windows -- closing the window is not enough)
2. Reopen Claude Desktop
3. Try the tool again

This is the single most effective fix for Coppermind tools that seem broken. If a restart does not fix it, then run a health check (below).

Saw a "usage limit exceeded" message right after upgrading your Claude plan? Sign OUT and back in.#

If you just upgraded your Claude plan (for example, Pro to Max) and immediately hit a "usage limit exceeded" message even though your usage is low, the limit is being read from your old tier. This is an Anthropic-side caching behavior, not a Coppermind bug -- Coppermind does not set or enforce Claude's plan limits.

The fix is a full sign-out, not just a restart:

1. In Claude Desktop, sign out of your account
2. Sign back in
3. The new tier's limits load on a fresh session

A plain restart often does not clear this -- you need to sign out and back in so Claude re-reads your account tier.

When to Run a Health Check#

Run system when:

• Coppermind feels slow or unresponsive
• Search results are empty when they should not be
• You see error messages about services being unavailable
• A connected MCP (Google Calendar, Granola, etc.) stops working
• You want to verify everything is working before an important meeting

Running a Health Check#

"Check Coppermind health"

Or more directly:

"Is everything working?"

This calls system, which probes three core services and returns their status.

What Gets Checked#

Core Services#

Health Statuses#

Reading the Results#

All healthy (most common):

All Coppermind services healthy.
  Database: connected
  Gateway: connected
  Embedding: connected

One service down:

1 service needs attention.
  Database: connected
  Gateway: disconnected
  Embedding: connected

Recovery steps:
  - Gateway unreachable -- check your internet connection
  - If on VPN, verify api.coppermind.app is accessible
  - Try again in 30 seconds (may be a transient outage)

Connector Recovery Guide#

Every health check response includes a connector recovery guide -- step-by-step instructions for fixing disconnected MCP integrations. This is the most common issue beta testers hit.

Google Calendar#

Symptoms: Morning briefing shows no meetings. Auto-prep does not trigger.

Recovery:

1. Open Claude Desktop Settings (Cmd+,)
2. Go to Integrations > Google Calendar
3. Toggle off, wait 5 seconds, toggle back on
4. If that fails, click "Reconnect" to re-authorize

Quick test: Ask Claude to list your upcoming events. If it works, the connection is fine.

Google Drive#

Symptoms: Document ingestion from Drive fails. "Cannot access file" errors.

Recovery:

1. Open Claude Desktop Settings (Cmd+,)
2. Go to Integrations > Google Drive
3. Toggle off, wait 5 seconds, toggle back on
4. If that does not work, click "Reconnect" to re-authorize

Note: Reconnecting Drive does not affect your Coppermind data. Only the live connection to Drive is reset.

Granola#

Symptoms: Meeting transcripts are not being auto-ingested. ingest shows meetings but transcripts fail to fetch.

Recovery:

1. Check that the Granola desktop app is running
2. Verify Granola shows recent meetings in its own UI
3. In Claude, try: "Search Granola for my last meeting"
4. If Granola is unreachable, restart the Granola app

Slack#

Symptoms: Cannot pull messages or channel history from Slack.

Recovery:

1. Open Claude Desktop Settings (Cmd+,)
2. Go to Integrations > Slack
3. Toggle off, wait 5 seconds, toggle back on
4. If that fails, click "Reconnect" to re-authorize

Other Connectors (ClickUp, HubSpot, WhatsApp)#

General recovery pattern:

1. Check that the service is accessible in your browser
2. Toggle the integration off and on in Claude Desktop Settings
3. If that fails, re-authorize the connection
4. If multiple connectors are down simultaneously, restart Claude Desktop

Common Scenarios#

"Search returns no results"#

1. Run system to verify the embedding service is up
2. If embedding is disconnected, search cannot generate query vectors. Wait for the service to recover -- existing memories are not lost
3. If embedding is healthy, the issue may be that the client has very few memories. Run memory to check coverage

"Meeting prep brief is empty"#

1. Run system to verify the database is connected
2. If database is healthy, switch to the client and check memory count
3. A client with fewer than 3 memories gets a "raw" mode brief instead of a structured one. Ingest more content to improve briefs

"Store memory fails"#

1. Run system to verify the database and gateway are connected
2. If the gateway is down, the memory still stores but without an embedding. It will not appear in search results until the embedding is backfilled
3. Check the error code in the response -- SERVICE_UNAVAILABLE means transient failure, INVALID_INPUT means the content was empty or too long

"Auto-ingest is not picking up meetings"#

1. Verify the calendar connector is healthy (run health check)
2. Verify the transcript source (Granola) is connected
3. Run ingest to see what is in the queue
4. If meetings show but have match_confidence: "none", the meeting title did not match any client mind. Log the meeting manually with the correct client mind

"Everything is slow"#

1. Run system -- look for "degraded" statuses
2. The gateway uses exponential backoff for retries (1s, 2s, 4s). If you are seeing delays, it may be retrying transient failures
3. Check your internet connection -- all gateway calls go through api.coppermind.app

Embedding Service Degradation#

When the embedding service is unavailable, Coppermind enters degraded mode:

Memories stored without embeddings are automatically detected by the system. They will appear in search results once the embedding service recovers and the embeddings are generated.

Key Details#

• Health check never fails as a tool call. It always returns a result. Individual service failures are reported in the response, not as tool errors.
• The connector recovery guide is always included, even when all connectors are healthy. This way you have the instructions available when you need them.
• Health check does not require an active client mind. You can run it before switching to any client.
• Probing is lightweight. The check runs a simple SELECT against the database, a GET against the gateway, and a small test embedding. It does not modify any data.