Error Handling and Troubleshooting

How to understand and resolve errors from Armbrain MCP tools, and how to diagnose common issues during setup and daily use.

Error Response Format

All Armbrain tool errors return a structured JSON object:

{
  "error": true,
  "code": "NO_ACTIVE_MIND",
  "message": "No active client. Call switch_client first."
}

The code field identifies the error type. The message field provides a human-readable explanation and, in many cases, a suggested action.

Error Code Reference

NO_ACTIVE_MIND

What it means: You tried to use a tool that requires an active client mind, but no client mind is selected.

When you see it: On any tool call except mind, switch_client, and the cross-client daily loop tools (briefing, briefing, memory, briefing).

How to fix:

"Switch to Acme Corp"

The active client mind resets every time the MCP server process restarts (e.g., when you reopen Claude Code). Always switch to your target client at the start of a session.

MIND_NOT_FOUND

What it means: No client mind matches the name you provided, and create_new was not set to true.

When you see it: When calling switch_client with a name that doesn't match any existing client mind.

How to fix: The error response includes a list of all existing client mind names so you can spot typos:

"Switch to Acm Corp"
→ Error: No mind matching 'Acm Corp'. Existing minds: Acme Corp, Bluebell, Julica

Either fix the name or create a new client mind:

"Set up a new client called Acm Corp"

MIND_ARCHIVED

What it means: The client mind you're trying to switch to has been archived.

When you see it: When calling switch_client for an archived client.

How to fix: In the current version, unarchiving requires direct database access:

UPDATE client_minds SET archived_at = NULL WHERE slug = 'acme-corp';

An archive_mind tool with unarchive support is planned for a future release.

VALIDATION_ERROR

What it means: Content failed a guardrail check before storage. This is separate from parameter validation — guardrails check the content itself.

Common causes:

Tool	Trigger	Fix
`store_memory`, `memory`	Content exceeds 10,000 characters	Shorten the content or split into multiple memories
`ingest`	Content exceeds 50,000 characters	Trim or split the document
`ingest`	Transcript exceeds 150,000 characters	Split the transcript into multiple meeting entries
Any storage tool	Invalid UTF-8 encoding (bad characters)	Re-copy the text from the source — the original may have encoding issues
Any storage tool	Token budget exceeded (~100,000 tokens)	This is a safety limit for extremely large content. Break into smaller pieces

Note: Guardrails also scan content for prompt injection patterns and PII. These are flagged only, never blocked — you won't see a VALIDATION_ERROR for them. PII-containing memories are automatically tagged sensitive. See Memory Storage and Search for details.

INVALID_INPUT

What it means: A parameter is missing, malformed, or out of range.

Common causes:

Tool	Trigger	Fix
`store_memory`	Content empty	Provide content to store
`store_memory`	Summary exceeds 500 characters	Provide a shorter summary
`set_brand_voice`	JSON shape doesn't match expected structure	See the Brand DNA field definitions in the Brand DNA guide
`mind`	Invalid cadence or company_info shape	Provide valid JSON with required fields
`business_os`	CSV/JSON parse failure or no valid initiatives	Check your CSV format and column names
`business_os`	Status not one of the valid values	Use: `on_track`, `off_track`, `at_risk`, `complete`, `dropped`
`business_os`	Status not one of the valid values	Use: `not_started`, `in_progress`, `complete`, `blocked`, `cut`
`memory`	Datetime missing timezone info	Use ISO 8601 with timezone: `2026-03-21T10:00:00-05:00`

INVALID_BRAND_DNA

What it means: The Brand DNA JSON you provided doesn't match the expected schema.

How to fix: Check the field structures in the Brand DNA guide. Common issues:

tune requires a tone key (list of strings)
brand_positioning requires a category key (string)
stakeholders must be an array of objects, each with a name key
Maximum 50 stakeholders per client

SERVICE_UNAVAILABLE

What it means: The embedding service (Voyage AI via the gateway) is unreachable.

When you see it: On search_memory when embeddings can't be generated for the query.

Impact: Semantic search is impossible without embeddings. However:

store_memory and memory will still store memories with embedding = NULL (they'll be missing from search results but available in meeting prep)
briefing continues working with non-embedding-based retrieval
get_campaign_history is unaffected (it queries by type, not by embedding)

How to fix: Check your internet connection and API key. The embedding service runs through the gateway at api.armbrain.io.

MEMORY_NOT_FOUND

What it means: The memory ID you're trying to hide doesn't exist, or it belongs to a different client mind.

When you see it: On memory when the UUID is wrong or the memory belongs to another client.

How to fix: Search for the memory first to get the correct ID, or verify you're switched to the right client.

ACCESS_DENIED

What it means: Your API key doesn't have access to the selected client mind.

When you see it: When trying to access a client mind owned by a different customer, or a client mind you haven't been granted access to.

How to fix: Verify you're using the correct API key. If you're trying to access a shared client mind (team feature), confirm that access has been granted.

ACCOUNT_INACTIVE

What it means: Your customer account exists but has been deactivated.

When you see it: During gateway authentication, when your API key is valid but the account's active flag has been set to false.

How to fix: Contact support. This typically happens when a trial expires or an account is suspended. Your data is still there — it just needs to be reactivated.

PROVISIONING_ERROR

What it means: The gateway couldn't identify your account during startup provisioning.

When you see it: When your API key is invalid or the gateway is unreachable.

How to fix: Verify that your API key is entered correctly in your Connector settings. Go to Claude Desktop Settings > Connectors > Armbrain > Configure and confirm the key. If the problem persists, check that you can reach api.armbrain.io in your browser.

MIGRATION_REQUIRED

What it means: A tool requires a database table that hasn't been created yet (migration not applied).

When you see it: On Business OS tools (business_os, get_rocks, etc.), daily loop tools (memory, etc.), or memory (commitment tracking).

How to fix: This is handled automatically by the server. If you see this error, try again in a few minutes or contact support at armbrain@volacci.com.

Connection Issues

Armbrain runs as a remote MCP connector. If your connection fails, Claude Desktop will show an error when you try to use any Armbrain tool.

Issue	What You See	Fix
No API key	Tools fail with authentication error	Go to Claude Desktop Settings > Connectors > Armbrain > Configure, and enter your API key
Invalid API key	Provisioning failure	Verify the key is correct in your Connector settings
Server unreachable	Connection timeout or failure	Check your internet connection. If the problem persists, the server may be temporarily down -- try again in a few minutes
Embedding service down	Search returns no results, but storage works	This is temporary. Memories will still be stored and available in meeting prep. Search will resume when the service recovers

Common Issues and Solutions

"My search isn't returning relevant results"

Check that you're switched to the right client. All searches are scoped to the active client mind.
The similarity threshold is 0.3. Very generic queries may not match specific memories. Try more specific terms.
Memories stored without embeddings (due to service unavailability) won't appear in search results. They'll still show up in meeting prep.
Time decay applies. Older memories with slightly higher raw similarity may rank lower than recent ones. This is intentional -- recent context is usually more relevant.

"My meeting brief is missing information"

Minimum 3 memories required. Below that threshold, Armbrain returns raw data instead of a structured brief.
Sensitive memories are restricted. Memories classified as sensitive or cmo-only are excluded from restricted-role views and client-safe outputs.
The limit parameter defaults to 50. For clients with extensive history, increase it: "Prep my meeting with a limit of 100".

"I accidentally stored wrong information"

Hide the incorrect memory: "Hide that memory about LinkedIn ads"
Store the corrected version: "Remember: We're resuming LinkedIn ads in Q3"

There's no edit-in-place yet. The pattern is: hide the wrong one, store the right one.

"I can't tell if the client switch worked"

After switching, Armbrain confirms with the client mind name and memory count. If you're unsure:

"Which client am I on?"
"List my clients"

Key Details

Errors include context. Most error responses include suggestions for how to fix the issue. Read the message field.
Idempotent operations. Hiding an already-hidden memory returns success. Logging the same calendar event (by calendar_event_id) upserts rather than creating a duplicate.
Graceful degradation. When the embedding service is down, memory storage continues but search is unavailable. When optional tables are missing, tools that don't need them still work.
Structured logging. Server errors are logged as structured JSON to stderr with timestamps, tool names, and client mind IDs for debugging.