What to do if djay reports an error with the djay Media Library database

The djay Media Library stores your playlists, history, queue, cue points, loops, and other track-specific metadata.

If the database becomes corrupted or incompatible, djay will show an error on launch. This guide explains what the error means, how automatic backups work, and how to restore a working version of the database on iOS or macOS.

Understanding the Issue

The djay Media Library database is where djay keeps essential user data:

• Playlists
• History
• Queue
• Cue points, loops, and other track metadata

In rare cases, the database can become corrupted or incompatible — for example, after switching between different djay versions. When this happens, you may see one of the following alerts:

macOS Examples

iOS Examples

note

If possible, please contact our support team and attach the corrupted database. This helps us improve the stability of djay.

Automatic Backups (iOS and macOS)

djay automatically maintains backups of your Media Library:

• A backup is created each time you launch djay, unless one already exists for that day.
• Up to 10 backups are kept. Older backups are deleted automatically.
• Backup folders are named by date (e.g., 2023-03-18).

The backups are stored in the following locations:

• iOS: On My iPhone/iPad → djay → User Data → Backups
• macOS: ~/Music/djay/Backups

Restore Instructions

macOS

How to restore a djay Media Library backup on macOS

When the error appears, you may see one of the following alerts:

• Error reading djay Media Library database
• Version mismatch in djay Media Library database

djay will then offer options such as:

• Quit — closes the app so you can restore a backup
• Continue — creates a new empty database (your old one is saved)
• Learn More — opens this support article

How to restore a backup from ~/Music/djay/Backups

1. Quit djay.
2. Open Finder and go to your Music folder.
3. Open the djay folder. Rename the existing djay Media Library file by adding something like -old or today’s date to the end of the name.
4. Open the Backups folder inside the same directory.
5. Open the folder for the date you want to restore.
6. Locate djay Media Library, then Option-drag it into the main djay folder to copy it.
7. Launch djay again — your restored library will load.

note

If the restored version still fails to load, try an older backup folder.

iOS

How to restore a djay Media Library backup on iOS

When the error appears, you may see one of the following alerts:

• Error reading djay Media Library database
• Version mismatch in djay Media Library database

You will then have these options:

• Continue — creates a new empty database (the existing one is preserved).
• Learn More — opens this support article.

How to restore a backup from On My iPhone/iPad → djay → User Data → Backups

1. Open the Files app.
2. Tap Browse → On My iPad/iPhone.
3. Open the djay folder, then open User Data.
4. Long-press djay Media Library and choose Rename
   (we recommend adding today’s date to the end of the name).
5. Open the Backups folder.
6. Open the folder for the date you want to restore.
7. Long-press djay Media Library and choose Copy.
8. Go back to the User Data folder.
9. Long-press an empty area and choose Paste.
10. Launch djay — the restored Media Library will load.

note

If the most recent backup does not resolve the issue, repeat the process with an older backup folder.