# Troubleshooting

## Services Not Starting (PM2)

**Symptom**: `pm2 list` shows services as `errored` or `stopped`.

**Steps**:

1. View the error logs:
   ```bash
   pm2 logs <service-name> --lines 50
   ```

2. Check for port conflicts:
   ```bash
   lsof -i :7100   # channel server
   lsof -i :8087   # notifications
   lsof -i :8084   # calendar
   lsof -i :8086   # status
   ```
   Kill the conflicting process or change the port in `config/system.json`.

3. Verify Node.js version:
   ```bash
   node --version   # must be 22+
   ```

4. Re-run the build for a specific service:
   ```bash
   cd <installPath>/services/<name>
   npm install && npm run build
   pm2 restart <name>
   ```

5. Reload the PM2 ecosystem config:
   ```bash
   pm2 delete all
   pm2 start <installPath>/ecosystem.config.js
   pm2 save
   ```

**PM2 daemon not running**:
```bash
pm2 resurrect     # restore last saved process list
# or
pm2 start <installPath>/ecosystem.config.js
```

---

## Claude Code Auth Issues

**Symptom**: The conductor agent exits immediately with an auth error, or `claude` prompts for login every session.

**Steps**:

1. Log in to Claude Code:
   ```bash
   claude auth login
   ```

2. Verify the session:
   ```bash
   claude auth status
   ```

3. If the agent runs as a different user (e.g. via PM2 with a custom user), log in as that user:
   ```bash
   sudo -u <user> claude auth login
   ```

4. Check that `ANTHROPIC_API_KEY` is set in the conductor's `.env` file and referenced in the PM2 ecosystem config:
   ```bash
   cat <installPath>/agents/conductor/.env
   ```

5. If using the API key mode (not OAuth), make sure the key is valid at [console.anthropic.com](https://console.anthropic.com).

---

## OAuth Not Working (Dashboard Login)

**Symptom**: Clicking "Sign in with Google" redirects to an error page, or login completes but you see "access denied".

**Steps**:

1. Verify `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in `config/system.json` match the credentials downloaded from Google Cloud Console.

2. Check the authorized redirect URI in Google Cloud Console matches exactly:
   ```
   http://localhost:3006/api/auth/callback/google
   ```
   No trailing slash. No `https` if running locally.

3. Ensure your email is added as a test user in the Google OAuth consent screen (for External apps in Testing mode).

4. Check the dashboard logs:
   ```bash
   pm2 logs main --lines 100
   ```

5. Clear your browser cookies for `localhost:3006` and try again.

6. If the consent screen shows "App not verified", your OAuth app is in testing mode — this is expected. Click "Continue" to proceed.

---

## Channel Server Connection Refused

**Symptom**: The dashboard shows a connection error, or agents report they cannot reach the channel server.

**Steps**:

1. Check if the channel server is running:
   ```bash
   pm2 list | grep channel
   curl http://localhost:7100/health
   ```

2. View channel server logs:
   ```bash
   pm2 logs channel-server --lines 50
   ```

3. Check if the TypeScript build is up to date:
   ```bash
   cd <installPath>/services/channel-server
   npm run build
   pm2 restart channel-server
   ```

4. Verify the `ONE_CHANNEL_SECRET` in the conductor's `.env` matches the value in the channel server's environment (set during installation).

5. If the dashboard is on a different host or port, check CORS configuration in `core/tools/channel-server/server.ts`.

---

## Agent Not Responding

**Symptom**: Messages sent via the dashboard get no reply, or the conductor appears to be stuck.

**Steps**:

1. Check if the conductor is running:
   ```bash
   pm2 list | grep conductor
   pm2 logs conductor --lines 50
   ```

2. Check the channel server for queued messages:
   ```bash
   curl http://localhost:7100/conversations/main/messages \
     -H "Authorization: Bearer <ONE_CHANNEL_SECRET>"
   ```

3. Restart the conductor:
   ```bash
   pm2 restart conductor
   ```

4. If the conductor exited due to a context limit or error, check its log for the last action and resume:
   ```bash
   pm2 logs conductor --lines 200
   ```

5. If the `session-start` hook is failing (preventing context restoration), disable it temporarily:
   - Edit `.claude/settings.json` in the conductor directory
   - Remove the `UserPromptSubmit` hook entry
   - Restart the conductor

6. Verify `CLAUDE.md` is present in the conductor directory:
   ```bash
   ls <installPath>/agents/conductor/CLAUDE.md
   ```

---

## Module Installation Failures

**Symptom**: `./scripts/add-module.sh <name>` fails with an npm or build error.

**Steps**:

1. Ensure Node.js 22+ is active:
   ```bash
   node --version
   ```
   If using nvm: `nvm use 22`

2. Clear npm cache and retry:
   ```bash
   cd <installPath>/services/<name>
   rm -rf node_modules
   npm install
   npm run build
   ```

3. Check for TypeScript compilation errors:
   ```bash
   cd <installPath>/services/<name>
   npx tsc --noEmit
   ```

4. Verify the module's `data/` directory exists and is writable:
   ```bash
   mkdir -p <installPath>/services/<name>/data
   ```

5. For `better-sqlite3` native addon errors, rebuild it:
   ```bash
   cd <installPath>/services/<name>
   npm rebuild better-sqlite3
   ```

6. Check that all required dependencies (other modules) are already installed and running. For example, installing `calendar` without `notifications` will cause `calendar` to fail at runtime.

---

## Collecting Debug Information

When filing a bug report, include the output of:

```bash
./scripts/health-check.sh
pm2 list
node --version
cat config/system.json | grep -v secret | grep -v key | grep -v password
```
