# Debugging Knowledge Base

> Every solved problem becomes a note here.

---

## Container Issues

### Memory exhaustion causing exec timeouts
- **Symptom**: All exec commands hang, but user's shell works fine
- **Root cause**: Machine memory fully used (docker system prune -f freed 5.6GB)
- **Fix**: `sudo sync && echo 3 | sudo tee /proc/sys/vm/drop_caches`
- **Prevention**: Run `docker system prune` periodically

### Background git clone blocking main session
- **Symptom**: Agent exec hangs, user's shell normal
- **Root cause**: Multiple git clone processes consuming network/memory simultaneously
- **Fix**: `sudo pkill -9 git`
- **Prevention**: Never run multiple large network operations concurrently

---

## Git Issues

### git worktree pointing to empty bare repo
- **Symptom**: `~/github/data-service-infra-ai-configurations/` shows as empty directory
- **Root cause**: worktree target bare repo has no content
- **Fix**: Re-clone repo into ~/github/ directory

### Main session PTY blocking
- **Symptom**: exec tool times out, subagent works fine
- **Root cause**: Unknown, possibly PTY state corruption
- **Fix**: Restart openclaw gateway (`openclaw gateway restart`)

---

## Feishu Issues

### Feishu API network unreachable
- **Symptom**: API returns 503 or times out
- **Root cause**: Machine has unstable network to open.feishu.cn
- **Status**: Cannot send proactive alerts until network recovers

---

## Container Gateway Port Conflict
Source: skills/team-admin/team-employee/SKILL.md
- **Symptom**: Container fails to start with "Gateway failed to start: another gateway instance is already listening on ws://127.0.0.1:18791"
- **Root cause**: Host machine already has an OpenClaw Gateway running on the same port the container tries to use (host mode)
- **Fix**: Use **bridge network mode** instead of host mode in docker-compose; container gets its own IP on docker network, no port conflict
- **Why Feishu still works**: Feishu connects via WebSocket as outbound connection from container to Feishu servers, no port exposure needed

## Missing Feishu SDK in Container
Source: skills/team-admin/team-employee/SKILL.md
- **Symptom**: `[plugins] feishu failed to load: Cannot find module '@larksuiteoapi/node-sdk'`
- **Fix**: `docker exec --user root <container-name> npm install -g @larksuiteoapi/node-sdk && docker restart <container-name>`

## GATEWAY_PORT Env Var Not Passed to Container
Source: skills/team-admin/team-employee/SKILL.md
- **Symptom**: `error: option '--port <port>' argument missing`
- **Root cause**: Docker compose variable `${GATEWAY_PORT}` not expanded when env var is unset
- **Fix**: Use `sh -c "... --port ${GATEWAY_PORT:-18791} ..."` — the `:-18791` provides a default value

## GitHub PR "Head sha can't be blank" Error
Source: skills/team-admin/github-pr/SKILL.md
- **Symptom**: PR creation fails with "Head sha can't be blank"
- **Root cause**: Branch not yet pushed to remote
- **Fix**: Push branch first with `git push origin <branch>`, then create PR
- **Related**: If branch already has a PR, use `gh pr view` to check existing PR status instead of creating a duplicate

## Feishu Bot Not Receiving Messages (WebSocket Setup)
Source: quick-start/how-to-configuration-feishu-bot-for-openclaw.md
- **Symptom**: Bot added to chat but not receiving messages
- **Root cause**: WebSocket long connection not enabled in Feishu Open Platform console
- **Fix**: In Feishu console → Events and Callbacks → select "Use persistent connection (长连接)" → set endpoint `http://<server-ip>:18791/webhook/feishu`
- **Gotcha**: Server IP must be publicly accessible; bot must be published and approved

---

## OpenClaw Agent Issues

### minimax API key not found (bingwang container)
- **Symptom**: "No API key found for provider minimax" error in DM
- **Root cause**: Auth profile resolution differs between containers despite identical config
- **Fix**: Compare auth-profiles.json between bearc (working) and bingwang; add missing `lastGood` field
- **Key difference found**: bearc has `auth.json` and `lastGood` field, bingwang does not