musicbrainz-cleaner/TROUBLESHOOTING.md

# 🚨 MusicBrainz Cleaner Troubleshooting Guide

This guide documents common issues encountered when starting and running the MusicBrainz cleaner, along with their solutions.

## 📋 Key Files for New Sessions

When starting a new chat session, reference these files in order:

1. **`README.md`** - Quick start guide and basic usage
2. **`PRD.md`** - Technical specifications and requirements  
3. **`SETUP.md`** - Detailed setup instructions
4. **`TROUBLESHOOTING.md`** - This file - common issues and solutions
5. **`start_services.sh`** - Automated service startup script
6. **`restart_services.sh`** - Quick restart script for after reboots

## Quick Diagnostic Commands

```bash
# Check if Docker is running
docker --version

# Check container status
cd ../musicbrainz-docker && docker-compose ps

# Check database logs
docker-compose logs db | tail -10

# Check web server logs
docker-compose logs musicbrainz | tail -10

# Test web server response
curl -s http://localhost:5001 | head -5

# Test database connection
docker-compose exec db psql -U musicbrainz -d musicbrainz_db -c "SELECT COUNT(*) FROM artist;"

# Test cleaner connection
cd ../musicbrainz-cleaner && docker-compose run --rm musicbrainz-cleaner python3 -c "from src.api.database import MusicBrainzDatabase; db = MusicBrainzDatabase(); print('Connection result:', db.connect())"
```

## Common Issues & Solutions

### 🚫 Issue 1: Database Connection Refused

**Error Message:**
```
Connection error: connection to server at "172.18.0.2", port 5432 failed: Connection refused
```

**Root Cause:** Database container not fully initialized or wrong host configuration

**Solutions:**

1. **Wait for database initialization:**
   ```bash
   cd ../musicbrainz-docker
   docker-compose logs db | grep "database system is ready"
   ```

2. **Fix host configuration in database.py:**
   ```python
   # Change this line in src/api/database.py:
   host='172.18.0.2'  # ❌ Wrong
   host='db'          # ✅ Correct
   ```

3. **Verify database is ready:**
   ```bash
   docker-compose exec db psql -U musicbrainz -d musicbrainz_db -c "SELECT COUNT(*) FROM artist;"
   ```

### 🚫 Issue 2: Test Shows 0% Success Rate

**Symptoms:** Test script reports 0% success despite finding artists in logs

**Root Cause:** Test script logic error - checking `'mbid' in result` where `result` is a tuple

**Solution:** Fix test script to extract song dictionary from tuple:
```python
# Wrong:
artist_found = 'mbid' in result

# Correct:
cleaned_song, success = result
artist_found = 'mbid' in cleaned_song
```

### 🚫 Issue 3: Port Already in Use

**Error Message:**
```
ports are not available: exposing port TCP 0.0.0.0:5000 ... bind: address already in use
```

**Solution:**
```bash
# Kill process using port 5000
lsof -ti:5000 | xargs kill -9

# Or use alternative port
MUSICBRAINZ_WEB_SERVER_PORT=5001 docker-compose up -d
```

### 🚫 Issue 4: Container Name Conflicts

**Error Message:**
```
Conflict. The container name ... is already in use
```

**Solution:**
```bash
# Stop and remove existing containers
docker-compose down

# Force remove specific container if needed
docker rm -f <container_name>

# Restart services
docker-compose up -d
```

### 🚫 Issue 5: Docker Not Running

**Error Message:**
```
Cannot connect to the Docker daemon
```

**Solution:**
```bash
# Start Docker Desktop
open -a Docker

# Wait for Docker to start, then restart services
./restart_services.sh
```

### 🚫 Issue 6: API Returns Empty Results

**Symptoms:** API calls return empty results even though database has data

**Root Cause:** MusicBrainz web server not fully initialized

**Solution:**
```bash
# Wait for web server to be ready
sleep 60

# Test API response
curl -s "http://localhost:5001/ws/2/artist/?query=name:The%20Beatles&fmt=json"
```

## Startup Checklist

Before running any tests, verify:

1. ✅ **Docker Desktop is running**
2. ✅ **All containers are up:** `docker-compose ps`
3. ✅ **Database is ready:** `docker-compose logs db | grep "ready"`
4. ✅ **Web server responds:** `curl -s http://localhost:5001`
5. ✅ **Database has data:** Check artist count in database
6. ✅ **Cleaner can connect:** Test database connection in cleaner

## Performance Issues

### Slow Processing
- **Cause:** Database queries taking too long
- **Solution:** Ensure database has proper indexes and is fully loaded

### Memory Issues
- **Cause:** Docker Desktop memory allocation too low
- **Solution:** Increase Docker Desktop memory to 8GB+

### Platform Warnings
- **Cause:** Apple Silicon (M1/M2) platform mismatch
- **Solution:** These warnings can be ignored - services work correctly

## Recovery Procedures

### Complete Reset
```bash
# Stop all services
cd ../musicbrainz-docker && docker-compose down

# Remove all containers and volumes (⚠️ WARNING: This deletes data)
docker-compose down -v

# Restart from scratch
./start_services.sh
```

### Quick Restart
```bash
# Quick restart (preserves data)
./restart_services.sh
```

## Getting Help

If you encounter issues not covered in this guide:

1. Check the logs: `docker-compose logs -f`
2. Verify system requirements are met
3. Try the complete reset procedure
4. Check the main README.md for additional troubleshooting steps

## Prevention Tips

1. **Always use the startup scripts** (`start_services.sh` or `restart_services.sh`)
2. **Wait for services to fully initialize** before running tests
3. **Use the startup checklist** before running any tests
4. **Keep Docker Desktop memory allocation** at 8GB or higher
5. **Use port 5001** if port 5000 is busy