# Troubleshooting

## collab-send: "FAIL: collab-mcp 401 unauthorized"

**Cause 1 — api_key not configured**
```bash
claude-collab-config set api_key cmcp_xxx.<secret>
```

**Cause 2 — api_key revoked**
The key was rotated/revoked on the server. Create a new one:
```bash
collab-mcp keys create claude-collab --scopes=read,write
claude-collab-config set api_key <new-key>
```

**Cause 3 — Wrong host / port**
```bash
claude-collab-config set mcp_url http://127.0.0.1:3010
# or wherever collab-mcp lives
```

**Verify with `collab-doctor`** — it probes `/api/messages?limit=1` and tells you exactly which layer broke.

## collab-send: "FAIL: rpc(send_message) timeout after 5000ms"

**Cause** — collab-mcp not reachable on the configured host/port.
```bash
# Test connectivity
curl http://127.0.0.1:3010/health
# Should return {"ok":true}

# If not: is collab-mcp running?
collab-mcp status
# or
ss -tlnp | grep 3010
```

## collab-read: "(no messages)" but you know there are messages

**Cause 1 — since_id too high**
Try `collab-read all 0 --limit=10` to see latest from the beginning.

**Cause 2 — wrong from_user**
The CLI filters by sender. Try `collab-read all` instead.

**Cause 3 — clock skew on server**
Use `--since-time=00:00` to ignore server-side time filters if any.

## require('@trustbaseai/claude-collab') returns MODULE_NOT_FOUND

**Cause** — npm install -g puts the package in a path Node's default `require` doesn't see.

**Fix A — use the bin instead of require**
```bash
collab-send baobei 'hello'  # works regardless of NODE_PATH
```

**Fix B — set NODE_PATH**
```bash
export NODE_PATH=$(npm root -g)
node -e "require('@trustbaseai/claude-collab')"
```

**Fix C — embed via createRequire (ESM projects)**
```js
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const collab = require('@trustbaseai/claude-collab');
```

## `collab-list --type=todos` returns nothing but todos exist

The collab-mcp `/api/pending` endpoint uses `type` filter that has known gaps
(messages + todos + reviews + commits). If type=all works but a specific
type doesn't, your collab-mcp version may be < v0.2.6. Upgrade:
```bash
npm install -g @trustbaseai/collab-mcp@latest
```

## Everything works but logs spam `[claude-collab] api_key not configured`

That's a one-shot warning when `api_key` is missing at request time. To
silence, just configure it:
```bash
claude-collab-config set api_key cmcp_xxx.<secret>
```