Health Check and Troubleshooting

How to diagnose infrastructure issues, check connector health, and recover from common problems using Armbrain'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.

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

This is the single most effective fix for Armbrain 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 an Armbrain bug -- Armbrain does not set or enforce Claude's plan limits.

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

In Claude Desktop, sign out of your account
Sign back in
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:

Armbrain 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 Armbrain health"

Or more directly:

"Is everything working?"

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

What Gets Checked

Core Services

Service	What It Does	What Happens If It Is Down
Database	Stores all memories, brand DNA, meeting logs, and Business OS data	Nothing works -- no reads or writes
Gateway	Routes API calls, handles authentication, serves prompts	Hosted mode fails; local-only features still work
Embedding	Generates vector embeddings for semantic search	Search and new memory storage degrade; existing data still accessible

Health Statuses

Status	Meaning
Healthy	Service is responding normally
Degraded	Service is reachable but responding slowly or with partial errors
Disconnected	Service is unreachable

Reading the Results

All healthy (most common):

All Armbrain 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.armbrain.io 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:

Open Claude Desktop Settings (Cmd+,)
Go to Integrations > Google Calendar
Toggle off, wait 5 seconds, toggle back on
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:

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

Note: Reconnecting Drive does not affect your Armbrain 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:

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

Slack

Symptoms: Cannot pull messages or channel history from Slack.

Recovery:

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

Other Connectors (ClickUp, HubSpot, WhatsApp)

General recovery pattern:

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

Common Scenarios

"Search returns no results"

Run system to verify the embedding service is up
If embedding is disconnected, search cannot generate query vectors. Wait for the service to recover -- existing memories are not lost
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"

Run system to verify the database is connected
If database is healthy, switch to the client and check memory count
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"

Run system to verify the database and gateway are connected
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
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"

Verify the calendar connector is healthy (run health check)
Verify the transcript source (Granola) is connected
Run ingest to see what is in the queue
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"

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

Embedding Service Degradation

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

Feature	Behavior in Degraded Mode
`store_memory`	Stores without embedding. Memory exists but is invisible to search
`search_memory`	Returns `SERVICE_UNAVAILABLE` error
`memory`	Stores without embedding
`briefing`	Still works using non-semantic retrieval (commitments, stakeholder data, recent facts)
`get_brand_voice`	Unaffected (no embedding needed)
`memory`	Returns `SERVICE_UNAVAILABLE` (needs embedding for fuzzy match)

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.