Skip to content
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””

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

  1. 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.

  2. 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.

  3. Restart or reload the MCP host so it starts without the old in-memory authorization state.

  4. Call lookup_discogs again and complete the fresh authorization flow.

Internal state database is corrupt

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

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 matching managed runtime was found. Either call setup_essentia through your agent (installs and activates without restart), or run reklawdbox setup from the CLI. Standard setup requires CPython 3.14 and installs the locked wheel-only manifest at ~/.local/share/reklawdbox/essentia-venv/bin/python; do not point normal configuration at a repository-local venv.

Verify the interpreter first:

Terminal window
brew install python@3.14
python3.14 --version
  • No supported CPython 3.14 — ensure Homebrew’s python3.14 is on PATH, then retry setup.
  • Binary wheel unavailable or pip failed — managed Essentia setup currently supports macOS 15 or newer on Apple Silicon. Check the OS, network, and the full error before retrying; setup never falls back to a source build.
  • Setup lock timed out — another CLI or MCP process is setting up the runtime. Let it finish, then retry. The lock file may remain on disk; the kernel lock, not file existence, controls ownership.
  • Manifest mismatch — remove an obsolete CRATE_DIG_ESSENTIA_PYTHON override and rerun setup. Expert overrides must match the documented Python and package versions exactly.

Each new generation is validated before activation. Ordinary venv, pip, import, or switch failures remove only the incomplete generation and leave the prior stable runtime in place. If stable-path validation fails, setup attempts an atomic restoration; if that restoration itself fails, setup reports the rollback failure and preserves the directly validated generation instead of deleting it.

Essentia stopped after config change

Section titled “Essentia stopped after config change”

The probe is memoized per process. Restart the MCP server after changing host configuration or environment variables. Use setup_essentia to install or recover a missing or invalid runtime; it does not reload a changed environment variable into an already-running process.

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 Manual configuration.

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