Troubleshooting

Troubleshooting

Common Issues

Claude doesn't respond in Discord

Symptoms: You send /enter, Claude processes the prompt, but no message appears in Discord.

Causes & Solutions:

1. Environment not injected — discord-send can't find DISCORD_TOKEN or DEFAULT_CHANNEL_ID

   • Check logs for export errors
   • Verify the tmux session has the env vars: docker compose exec bot tmux show-environment -t <session-name>

2. System prompt disabled — CLAUDE_SYSTEM_PROMPT=OFF means Claude doesn't know about discord-send

   • Remove or unset CLAUDE_SYSTEM_PROMPT in .env

3. Claude is still booting — waitForClaudeReady() timed out (60s) and the prompt was sent before Claude was ready

   • Check logs for "timeout waiting for Claude ready" warnings
   • The prompt is still queued and will be processed — wait longer

Cannot find module './generated/prisma'

The Prisma client wasn't copied to dist/generated/. Run:

pnpm build   # includes prisma generate + copy step

Or manually:

pnpm prisma generate
cp -r src/generated dist/

Slash commands not appearing

• Guild-scoped (REGISTER_GUILD_ID set): Commands appear instantly
• Global (no REGISTER_GUILD_ID): Can take up to 1 hour to propagate
• Verify the bot has applications.commands scope in the invite URL
• Check logs for command registration errors

tmux: server not found or session errors

# Check if tmux server is running
tmux list-sessions

# In Docker
docker compose exec bot tmux list-sessions

If no sessions exist, they'll be created lazily on next /enter.

Bot can't create channels

The bot needs ManageChannels permission in the Discord server. Check:

1. Bot role has Manage Channels permission
2. No channel/category permission overrides blocking the bot

Attachments not working

• Maximum file size: 25 MiB per attachment
• Files are saved to <workspace>/.uploads/ with a timestamp prefix
• Check workspace directory permissions
• Verify the workspace volume is mounted correctly in Docker

Database locked / migration errors

SQLite doesn't handle concurrent writes well. Ensure:

1. Only one bot instance is running against the same database
2. The ./data directory has correct permissions (UID 1000 in Docker)
3. No other process has a lock on the SQLite file

Claude starts but immediately exits

Check Claude Code authentication:

# In Docker
docker compose exec bot claude --version
docker compose exec bot claude login

# Local
claude --version
claude login

Memory usage grows over time

• SessionState Map is in-memory — many active sessions increase memory
• Use /delete to clean up unused rooms
• The bot doesn't persist session state to disk — restart clears the Map
• Each tmux session runs a separate Claude Code process

Debug Mode

Enable verbose logging:

LOG_LEVEL=debug

Or in Docker Compose:

environment:
  LOG_LEVEL: debug

This shows:

• Every message received and buffered
• Session ensure/create/resume decisions
• Tmux commands executed
• Environment injection details
• Authorization checks

Useful Commands

# List all tmux sessions
tmux list-sessions

# Attach to a session to see what Claude is doing
tmux attach -t claude-<channelId>

# Detach: press Ctrl+B, then D

# Kill a stuck session
tmux kill-session -t claude-<channelId>

# Check bot logs
docker compose logs bot --tail 100 -f

# Check database
docker compose exec bot npx prisma studio