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

# 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:

   cd ../musicbrainz-docker
   docker-compose logs db | grep "database system is ready"
   

2. Fix host configuration in database.py:

   # Change this line in src/api/database.py:
   host='172.18.0.2'  # ❌ Wrong
   host='db'          # ✅ Correct
   

3. Verify database is ready:

   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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

# 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