Skip to content

Troubleshooting

Common issues and solutions.

Common Issues

No Media Found

Symptom: process-new-media finds no files

Solutions: 1. Verify download paths in .env: 

grep DOWNLOAD_PATH .env

  1. Check files exist: 

    ls -la /path/to/downloads/music

  2. Check file extensions are supported: 

    # Supported audio: .mp3, .flac, .wav, .m4a, .ogg, .opus, .aac, .wma, .m4b

Symptom: OSError: Invalid cross-device link

Cause: Source and destination on different filesystems

Solution: This is expected - the system falls back to copying files.

Database Locked

Symptom: DatabaseError: database is locked

Solutions: 1. Check no other instance is running: 

ps aux | grep media-organizer

  1. Kill stale processes: 
    pkill -f media-organizer

Genre Validation Failures

Symptom: Files skipped due to invalid genre

Solutions: 1. Check genre quality report: 

./run.sh stats --genre-quality

  1. Add genre to exceptions: 

    ./run.sh edit-genre-catalog
# Select: [4] Manage exceptions

  2. Run genre backfill: 

    ./run.sh music-genre-backfill --execute

Symptom: NavidromeClientError: connection refused

Solutions: 1. Verify Navidrome is running: 

curl http://localhost:4533

  1. Check credentials in .env: 

    grep NAVIDROME .env

  2. Test connection: 

    ./run.sh navidrome-test

Metadata Enrichment Timeout

Symptom: Online enrichment takes too long

Solution: Increase delay between API calls: 

echo "MUSIC_METADATA_API_DELAY_SECONDS=2.0" >> .env

Debug Mode

Enable verbose logging:

export LOG_LEVEL=DEBUG
./run.sh process-new-media

Reset Database

To reset the organization database:

# Backup first!
cp data/organization.json data/organization.json.backup

# Reset
rm data/organization.json
./run.sh process-new-media --dry-run

Get Help

  • Check logs: tail -f logs/organizer.log
  • Run tests: ./run.sh test
  • Open issue on GitHub