Troubleshooting

Database connection

“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

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

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

“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://).

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”

Use the targeted recovery path below. It preserves enrichment and analysis caches, audit history, saved presets, and calibration/profile statistics.

Call lookup_discogs again. If it returns an auth_url, open it, approve access on Discogs, and call lookup_discogs again to finish or restart the normal authorization flow.
If the stored session is still unusable, run the supported targeted command in a terminal:
Terminal window
```
reklawdbox disconnect-broker
```
This clears only the current broker session: its credential in macOS Keychain and its matching metadata in the configured internal state database. CRATE_DIG_STORE_PATH is honored when it is set.
Restart or reload the MCP host so it starts without the old in-memory authorization state.
Call lookup_discogs again and complete the fresh authorization flow.

Internal state database is corrupt

This is a separate last resort for a database that cannot be opened, not an authentication reset. Close the MCP host, identify the effective CRATE_DIG_STORE_PATH (or the default ~/Library/Application Support/reklawdbox/internal.sqlite3), and move the file to a backup filename instead of deleting it. Restarting will create a new store.

Moving the file removes more than reconstructible caches from the active store: it also loses audit history and resolutions, saved scoring presets, calibration/profile statistics, and broker session metadata. The broker credential is separate in macOS Keychain; moving the database does not clear an orphaned Keychain credential. Keep the moved file until recovery is complete.

“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”

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

Essentia / audio analysis

“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

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

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

XML import

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

<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

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

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

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

Tools not visible in Claude Code

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

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

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

claude mcp remove -s user reklawdbox

Slow tool responses

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

General

“No changes to write”

No changes staged. Use update_tracks first, then write_xml.