Troubleshooting and Support

The fastest way to debug Coppermind is to classify the failure before you chase internals.

1. Start with doctor

Run:

coppermind doctor
coppermind doctor --check
coppermind daemon health

If these fail, the problem is usually local runtime state, not cloud auth.

coppermind doctor is the repair command.

2. If tools or hooks never appear

That is usually a client registration problem, not a memory backend problem.

Check:

• did you actually run the installer or patcher for that client?
• did you restart the client after changing config?
• is the client still pointing at an older config file?

Expected MCP tools are:

• memory_search
• memory_ingest
• memory_get
• memory_stats
• memory_delete

3. If the runtime is healthy but memory still does not appear

The common causes are:

• the client is talking to the wrong runtime
• the integration never registered correctly
• you are on the advanced cloud path when you thought you were on the local one

4. If cloud-connected calls fail with auth errors

Look for:

• 401
• 403
• invalid_token
• missing_authorization

That usually means wrong cloud credentials, wrong gateway URL, or the wrong account or plan for the route.

5. If cloud auth succeeds but memory still fails

That is usually the storage layer behind hosted sync or BYODB attach.

Look for:

• memory_backend_not_configured
• memory_backend_unavailable
• byodb_query_failed

6. Local MCP shape vs cloud MCP shape

Default local MCP:

{
  "mcpServers": {
    "coppermind": {
      "command": "coppermind",
      "args": ["mcp", "serve"]
    }
  }
}

Advanced cloud MCP:

{
  "mcpServers": {
    "coppermind": {
      "command": "npx",
      "args": ["-y", "@coppermind/mcp"],
      "env": {
        "COPPERMIND_API_KEY": "cm_live_xxx"
      }
    }
  }
}

If you intended the local-first path, make sure you are not accidentally testing the cloud-connected one.

7. Before you ask for help

Include:

• which client you are using
• whether you are in local, hosted sync, or BYODB mode
• whether coppermind doctor passes
• the exact error code
• whether tools or hooks appear at all

That is usually enough to isolate the failure quickly.