Skip to content
reklawdbox reklawdbox

Troubleshooting

Database connection

Section titled “Database connection”

”Cannot open database” or “database is locked”

Section titled “”Cannot open database” or “database is locked””

Rekordbox holds an exclusive lock. Close it completely (check for background processes), then restart the MCP server.

”Failed to open database” or path errors

Section titled “”Failed to open database” or path errors”

Auto-detection failed. Set REKORDBOX_DB_PATH in your MCP config to the full path of master.db (default: ~/Library/Pioneer/rekordbox/master.db).

”Not a database” or decryption errors

Section titled “”Not a database” or decryption errors”

SQLCipher mismatch or corrupted DB. Ensure you’re using the reklawdbox binary (bundles correct SQLCipher). If corrupted, restore from master.backup.db / master.backup2.db / master.backup3.db in the same directory.

Discogs authentication

Section titled “Discogs authentication”

”Invalid broker URL in REKLAWDBOX_DISCOGS_BROKER_URL”

Section titled “”Invalid broker URL in REKLAWDBOX_DISCOGS_BROKER_URL””

Broker URL is invalid. Remove custom REKLAWDBOX_DISCOGS_BROKER_URL and REKLAWDBOX_DISCOGS_BROKER_TOKEN overrides to use built-in defaults. If self-hosting, verify the URL includes the scheme (https://).

”Discogs sign-in is still pending”

Section titled “”Discogs sign-in is still pending””

Browser authorization wasn’t completed. Open the auth_url in your browser, approve on Discogs, then call lookup_discogs again.

”Discogs broker session is missing or expired”

Section titled “”Discogs broker session is missing or expired””

Call lookup_discogs again to start a new auth flow. If that fails, hard reset:

  1. Close the MCP host process (e.g., quit Claude Code or Claude Desktop).

  2. Delete the internal database — or just the session table:

    Terminal window
    # delete the whole file
    rm ~/Library/Application\ Support/reklawdbox/internal.sqlite3
    

    # or just clear the session table
    sqlite3 ~/Library/Application\ Support/reklawdbox/internal.sqlite3 \
      "DELETE FROM broker_discogs_session;"

  3. Restart the MCP host.

  4. Call lookup_discogs to start fresh authentication.

”broker … HTTP 401”

Section titled “”broker … HTTP 401””

REKLAWDBOX_DISCOGS_BROKER_TOKEN doesn’t match the deployed broker. Check for copy-paste errors (trailing spaces, wrong quotes).

“broker … HTTP 404/410”

Section titled ““broker … HTTP 404/410””

Device flow expired before browser authorization completed. Call lookup_discogs again — complete the browser step promptly.

Essentia / audio analysis

Section titled “Essentia / audio analysis”

”Essentia not available”

Section titled “”Essentia not available””

No installation found. Either call setup_essentia through your agent (installs and activates without restart), or run reklawdbox setup from the CLI.

Essentia stopped after config change

Section titled “Essentia stopped after config change”

The probe is memoized per process. Restart the MCP server, or call setup_essentia to force a re-probe.

Audio analysis fails for specific tracks

Section titled “Audio analysis fails for specific tracks”

Unsupported codec or corrupted file. Supported formats: FLAC, MP3, WAV, M4A, AAC, AIFF. OGG and WMA are not supported.

XML import

Section titled “XML import”

Metadata didn’t update after import

Section titled “Metadata didn’t update after import”

Rekordbox reimport bug (since RB 5.6.1). Right-click playlist → Import To Collection, then select all (Cmd+A), right-click → Import To Collection again. The second pass forces metadata overwrite.

Import fails with no error

Section titled “Import fails with no error”

<COLLECTION Entries="N"> count doesn’t match actual tracks. Shouldn’t happen with reklawdbox — file a bug if it does.

Tracks appear as missing/offline

Section titled “Tracks appear as missing/offline”

File paths in the XML don’t match disk locations. The Rekordbox DB paths are stale (files moved/renamed). Fix locations in Rekordbox first, then re-export.

MCP host connection

Section titled “MCP host connection”

Server doesn’t start or disconnects

Section titled “Server doesn’t start or disconnects”

Wrong path or missing permissions. Verify the binary path and run chmod +x ./target/release/reklawdbox.

Setup says ~/Music does not exist

Section titled “Setup says ~/Music does not exist”

Create it with mkdir ~/Music, then re-run reklawdbox setup. Alternatively, create .mcp.json manually in whichever directory you prefer — see Adding to other directories.

Tools not visible in Claude Code

Section titled “Tools not visible in Claude Code”

Reklawdbox tools are scoped to ~/Music by default. Start Claude Code from that directory:

Terminal window
cd ~/Music && claude

If the tools still don’t appear, check that ~/Music/.mcp.json exists and contains a reklawdbox entry. Run reklawdbox setup to recreate it.

Tools appearing in every project

Section titled “Tools appearing in every project”

A global registration in ~/.claude.json overrides project scoping. This was the default before v0.20. Remove it:

Terminal window
claude mcp remove -s user reklawdbox

Slow tool responses

Section titled “Slow tool responses”

First-run analysis and enrichment are slow (decoding files, API calls). Subsequent calls use cache. This is expected.

General

Section titled “General”

”No changes to write”

Section titled “”No changes to write””

No changes staged. Use update_tracks first, then write_xml.

Still stuck?

Section titled “Still stuck?”