teto_ai/docs/troubleshooting.md

# Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the Discord Teto Bot. Issues are organized by category with step-by-step solutions.

## 🔍 Quick Diagnostics

### Basic Health Check
```bash
# Check if container is running
docker compose ps

# Check recent logs
docker compose logs --tail=50

# Check bot status in Discord
# Send: teto status
```

### File System Check
```bash
# Verify output directory
ls -la ./output/

# Check container volume mount
docker inspect teto_ai | grep -A 5 "Mounts"

# Check disk space
df -h ./output/
```

## 🐳 Docker Issues

### Container Won't Start

**Problem**: Container fails to start or exits immediately.

**Diagnosis**:
```bash
# Check container logs
docker compose logs teto_ai

# Check if ports are in use
netstat -tulpn | grep -E '(5901|3000)'

# Verify environment variables
docker compose config
```

**Solutions**:

1. **Missing Environment Variables**:
   ```bash
   # Ensure USER_TOKEN is set
   echo $USER_TOKEN
   
   # Create .env file if missing
   echo "USER_TOKEN=your_token_here" > .env
   ```

2. **Port Conflicts**:
   ```bash
   # Kill processes using required ports
   sudo lsof -ti:5901 | xargs kill -9
   sudo lsof -ti:3000 | xargs kill -9
   
   # Or modify docker-compose.yml to use different ports
   ```

3. **Insufficient Resources**:
   ```bash
   # Check available memory
   free -h
   
   # Check disk space
   df -h
   
   # Increase Docker memory limits if needed
   ```

### Container Crashes During Runtime

**Problem**: Container starts but crashes during operation.

**Common Causes**:
- Out of memory during video processing
- Discord API rate limiting
- Audio/video dependency issues
- Volume mount problems

**Solutions**:

1. **Memory Issues**:
   ```bash
   # Monitor container memory usage
   docker stats teto_ai
   
   # Increase container memory in docker-compose.yml
   services:
     teto_ai:
       mem_limit: 2g
       memswap_limit: 2g
   ```

2. **Audio/Video Dependencies**:
   ```bash
   # Rebuild container with fresh dependencies
   docker compose down
   docker compose build --no-cache
   docker compose up
   ```

### Volume Mount Issues

**Problem**: Recordings not appearing in `./output/` directory.

**Diagnosis**:
```bash
# Check if volume is mounted
docker inspect teto_ai | grep -A 10 "Mounts"

# Check container can write to volume
docker exec -it teto_ai touch /tmp/output/test_file
ls -la ./output/test_file
```

**Solutions**:

1. **Permission Issues**:
   ```bash
   # Fix ownership
   sudo chown -R $(id -u):$(id -g) ./output/
   
   # Set proper permissions
   chmod 755 ./output/
   ```

2. **Volume Not Mounted**:
   ```bash
   # Verify docker-compose.yml has correct volume mapping
   volumes:
     - ./output:/tmp/output
   
   # Recreate container
   docker compose down
   docker compose up --build
   ```

## 🎥 Recording Issues

### Bot Won't Join Voice Channel

**Problem**: `xbox record that` fails with voice connection errors.

**Error Messages**:
- "Failed to join voice channel"
- "You need to be in a voice channel"
- No response from bot

**Solutions**:

1. **User Not in Voice Channel**:
   - Ensure you're connected to a voice channel before commanding
   - Try leaving and rejoining the voice channel
   - Check if voice channel has user limits

2. **Permission Issues**:
   ```bash
   # Verify bot has required permissions:
   # - Connect to voice channels
   # - Use voice activity
   # - View channels
   ```

3. **Discord API Issues**:
   ```bash
   # Check Discord status
   curl -s https://discordstatus.com/api/v2/status.json
   
   # Restart container to refresh connections
   docker compose restart teto_ai
   ```

4. **Voice Dependencies**:
   ```bash
   # Check voice libraries in container
   docker exec -it teto_ai npm list | grep -E "(opus|sodium)"
   
   # Verify FFmpeg installation
   docker exec -it teto_ai which ffmpeg
   ```

### No Audio/Video Captured

**Problem**: Recording starts but produces empty or no files.

**Diagnosis**:
```bash
# Check if file was created
ls -la ./output/recording-*.mkv

# Check file size
du -h ./output/recording-*.mkv

# Check container logs during recording
docker compose logs -f teto_ai
```

**Solutions**:

1. **User Has No Video/Audio**:
   - Ensure the recorded user has their camera on
   - Verify user is speaking/has audio activity
   - Check Discord's "Camera" and "Go Live" permissions

2. **FFmpeg Issues**:
   ```bash
   # Test FFmpeg in container
   docker exec -it teto_ai ffmpeg -version
   
   # Check codec support
   docker exec -it teto_ai ffmpeg -codecs | grep -E "(opus|h264|vp8)"
   ```

3. **Stream Connection Problems**:
   ```bash
   # Look for stream errors in logs
   docker compose logs teto_ai | grep -i "stream\|ffmpeg\|error"
   
   # Restart and try again
   docker compose restart teto_ai
   ```

### Recording Stops Immediately

**Problem**: Recording starts but stops within seconds.

**Common Causes**:
- Target user leaves voice channel
- Voice connection drops
- Stream connection fails
- Container resource limits

**Solutions**:

1. **User Connectivity**:
   - Ensure target user stays in voice channel
   - Check user's internet connection stability
   - Verify user hasn't muted/disabled video

2. **Container Resources**:
   ```bash
   # Check resource usage during recording
   docker stats teto_ai
   
   # Increase limits if needed
   # In docker-compose.yml:
   mem_limit: 2g
   ```

## 🔌 Discord API Issues

### Bot Not Responding

**Problem**: Bot doesn't respond to any commands.

**Diagnosis**:
```bash
# Check if bot is online in Discord
# Check container logs
docker compose logs --tail=100 teto_ai

# Check Discord connection
docker compose logs teto_ai | grep -i "discord\|login\|ready"
```

**Solutions**:

1. **Invalid Token**:
   ```bash
   # Verify token is correct and not expired
   echo $USER_TOKEN | cut -c1-20
   
   # Update token if needed
   export USER_TOKEN="new_token_here"
   docker compose restart teto_ai
   ```

2. **Rate Limiting**:
   ```bash
   # Check for rate limit messages in logs
   docker compose logs teto_ai | grep -i "rate\|limit"
   
   # Wait and restart if rate limited
   sleep 300
   docker compose restart teto_ai
   ```

3. **Discord Outage**:
   ```bash
   # Check Discord status
   curl -s https://discordstatus.com/api/v2/status.json | jq '.status.description'
   ```

### Commands Not Working

**Problem**: Bot responds but specific commands don't work.

**Diagnosis**:
```bash
# Check command handler logs
docker compose logs teto_ai | grep -i "command\|execute\|error"

# Test each command individually
# 1. hello teto
# 2. teto status  
# 3. xbox record that (in voice channel)
```

**Solutions**:

1. **Case Sensitivity**:
   - Commands are case-insensitive, but try exact case
   - Ensure no extra spaces or characters

2. **Permission Context**:
   - `teto` (DM pickup) only works in Direct Messages
   - Recording commands require voice channel membership
   - Some commands may require specific server permissions

3. **Command Conflicts**:
   ```bash
   # Check if multiple bots are responding
   # Ensure command syntax is exact
   # Verify bot has message read permissions
   ```

## 🔧 Development Issues

### Local Development Setup

**Problem**: Issues running bot locally without Docker.

**Solutions**:

1. **Node.js Version**:
   ```bash
   # Ensure Node.js 20+
   node --version
   
   # Install correct version with nvm
   nvm install 20
   nvm use 20
   ```

2. **Native Dependencies**:
   ```bash
   # Install build tools (Ubuntu/Debian)
   sudo apt install build-essential python3-dev
   
   # Install build tools (macOS)
   xcode-select --install
   
   # Rebuild native modules
   npm rebuild
   ```

3. **Audio Dependencies**:
   ```bash
   # Install system audio libraries
   # Ubuntu/Debian:
   sudo apt install libopus-dev libsodium-dev
   
   # macOS:
   brew install opus libsodium
   ```

### Module Import Errors

**Problem**: ES6 import/export errors.

**Solutions**:

1. **Package.json Configuration**:
   ```json
   {
     "type": "module",
     "engines": {
       "node": ">=20.0.0"
     }
   }
   ```

2. **File Extensions**:
   ```javascript
   // Always use .js extension in imports
   import videoService from './services/videoRecording.js';
   ```

## 📊 Performance Issues

### High CPU Usage

**Problem**: Container uses excessive CPU during recording.

**Solutions**:

1. **FFmpeg Optimization**:
   ```javascript
   // In videoConfig.js, optimize encoding settings
   FFMPEG_OPTIONS: {
     video: {
       preset: "ultrafast",  // Faster encoding
       crf: 28,             // Lower quality = less CPU
     }
   }
   ```

2. **Resource Limits**:
   ```yaml
   # In docker-compose.yml
   services:
     teto_ai:
       cpus: '2.0'
       mem_limit: 2g
   ```

### Large File Sizes

**Problem**: Recording files are too large.

**Solutions**:

1. **Encoding Settings**:
   ```javascript
   // Adjust quality settings in videoConfig.js
   FFMPEG_OPTIONS: {
     video: {
       crf: 28,           // Higher = smaller files
       preset: "medium",  // Better compression
     },
     audio: {
       bitrate: "96k"     // Lower bitrate
     }
   }
   ```

2. **Recording Duration**:
   ```javascript
   // Reduce auto-stop timeout
   AUTO_STOP_TIMEOUT: 15_000  // 15 seconds instead of 30
   ```

## 🆘 Emergency Recovery

### Complete System Reset

If all else fails, perform a complete reset:

```bash
# 1. Stop all containers
docker compose down

# 2. Remove containers and images
docker system prune -a

# 3. Remove volumes (WARNING: deletes recordings)
docker volume prune

# 4. Reset repository
git reset --hard HEAD
git clean -fd

# 5. Rebuild from scratch
docker compose up --build
```

### Backup Recovery

```bash
# Backup current recordings before reset
cp -r ./output ./output_backup_$(date +%Y%m%d_%H%M%S)

# Restore after reset
cp -r ./output_backup_*/* ./output/
```

## 📞 Getting Further Help

### Information to Gather

When seeking help, provide:

1. **System Information**:
   ```bash
   docker --version
   docker compose version
   uname -a
   ```

2. **Container Logs**:
   ```bash
   docker compose logs --tail=200 teto_ai > bot_logs.txt
   ```

3. **Configuration**:
   ```bash
   docker compose config > compose_config.yml
   ```

4. **Error Context**:
   - Exact command that failed
   - Error messages received
   - Steps leading to the issue
   - Expected vs actual behavior

### Debug Mode

Enable verbose logging:

```bash
# Set debug environment variable
export DEBUG=discord*,bot*

# Restart with debug logging
docker compose restart teto_ai

# Monitor detailed logs
docker compose logs -f teto_ai
```

## ✅ Verification Checklist

After resolving issues, verify everything works:

- [ ] Container starts without errors
- [ ] Bot appears online in Discord
- [ ] `hello teto` responds correctly
- [ ] `teto status` shows system information
- [ ] Can join voice channel with `xbox record that`
- [ ] Recording files appear in `./output/`
- [ ] Can stop recording manually
- [ ] DM pickup works (`teto` in DMs)
- [ ] Logs show no persistent errors

---

If problems persist after following this guide, consider reviewing the [architecture documentation](architecture.md) for deeper system understanding or checking the [setup guide](setup.md) for potential configuration issues.