Skip to content

FAQ

General

A required tool is not found

CrateDigger relies on three external tools. If any of them is missing or not on your system PATH, you will see an error on startup.

Tool Install
MediaInfo sudo apt install mediainfo / brew install media-info / scoop install mediainfo
FFmpeg (includes ffprobe) sudo apt install ffmpeg / brew install ffmpeg / scoop install ffmpeg
MKVToolNix (mkvpropedit, mkvextract, mkvmerge) sudo apt install mkvtoolnix / brew install mkvtoolnix / scoop install mkvtoolnix

If the tools are installed but not on your PATH (for example, a custom install location), tell CrateDigger where to find them in your config.toml (~/CrateDigger/config.toml on Linux or macOS, Documents\CrateDigger\config.toml on Windows):

[tool_paths]
mediainfo = "/usr/local/bin/mediainfo"
ffprobe = "/usr/local/bin/ffprobe"
mkvpropedit = "/usr/local/bin/mkvpropedit"
mkvextract = "/usr/local/bin/mkvextract"
mkvmerge = "/usr/local/bin/mkvmerge"

See getting started for full installation instructions.

What is the yellow "!" message on startup?

CrateDigger checks GitHub Releases at startup and prints a brief notice when a newer version is available. The yellow ! line tells you which version is out; the cyan line below it gives you the exact upgrade command to run.

The printed command is already correct for your install method. The three typical variants are:

  • pipx: pipx upgrade cratedigger
  • uv: uv tool upgrade cratedigger
  • pip or other: pip install --upgrade git+https://github.com/Rouzax/CrateDigger.git

To suppress the notice, set CRATEDIGGER_NO_UPDATE_CHECK=1 in your environment. The check is also silent automatically when stdout is not a TTY (pipes, cron jobs, CI systems).

The check is designed to stay out of your way. Results are cached locally at ~/.cache/CrateDigger/update-check.json (Linux), ~/Library/Caches/CrateDigger/update-check.json (macOS), or $env:LOCALAPPDATA\CrateDigger\Cache\update-check.json (Windows) for 24 hours on success, so it does not hit the network on every run. The network timeout is 2 seconds, and any failure is silently ignored. No usage data is sent; the check is a standard read-only request to the GitHub Releases API.

CrateDigger skips some of my files

CrateDigger only processes files with recognized media extensions. The defaults include .mp4, .mkv, .webm, .avi, .mov, .m2ts, .ts for video and common audio formats. Add extensions in the media_extensions config section if your files use something else.

Also check skip_patterns in your config. Files matching any skip pattern are excluded. The defaults skip */BDMV/* (Blu-ray disc structures) and Dolby* (demo content).

A file is classified as the wrong type

CrateDigger classified a concert as a festival set, or vice versa. Force the correct classification using path rules in content_type_rules:

[content_type_rules]
force_concert = ["Coldplay/*", "Pink Floyd/*"]
force_festival = ["*/Ultra Miami/*"]

Each rule is matched against the file's path relative to the source root. Coldplay/* matches any file directly inside a Coldplay folder. See Configuration: content type rules for more examples.

Where are my logs?

Each CrateDigger invocation writes its own log file to a per-platform directory:

Platform Directory
Linux ~/.local/state/CrateDigger/log/
macOS ~/Library/Logs/CrateDigger/
Windows $env:LOCALAPPDATA\CrateDigger\Logs\

Files are named {command}-{timestamp}-{hex}.log, for example identify-2026-05-07T13-44-01-a3f2.log. Every file captures DEBUG-level detail regardless of whether you pass --verbose or --debug on the command line. Log files older than 7 days are deleted automatically at startup. Because each run gets its own file, concurrent runs never conflict or interleave.

identify

"Error: credentials required"

Your 1001Tracklists email and password are not configured. Add them to your config.toml (~/CrateDigger/config.toml on Linux or macOS, Documents\CrateDigger\config.toml on Windows):

[tracklists]
email = "your@email.com"
password = "your-password"

Or set them as environment variables:

export TRACKLISTS_EMAIL="your@email.com"
export TRACKLISTS_PASSWORD="your-password"

$env:TRACKLISTS_EMAIL = "your@email.com"
$env:TRACKLISTS_PASSWORD = "your-password"

No results found for a file

CrateDigger builds the search query from the filename only. If the filename does not contain recognizable artist and event names, the search may return no results. Try:

  • Pass a manual search query: cratedigger identify recording.mkv --tracklist "Tiesto Ultra Miami 2025"
  • Pass the tracklist URL directly if you find it on 1001Tracklists: cratedigger identify recording.mkv --tracklist "https://www.1001tracklists.com/tracklist/..."
  • Rename the file to include the artist name and festival name before running identify

A file is skipped in auto mode

Auto mode requires the top result to score 150 or higher and the gap to the second result to be at least 20. If either threshold is not met, the file is skipped rather than guessing.

To handle skipped files, run the same folder interactively (without --auto) and pick manually:

cratedigger identify ~/Downloads/sets/

For files that are consistently hard to match automatically, use --tracklist to provide the URL directly.

Chapters are not embedding

Chapter embedding requires:

  1. The file must be MKV or WEBM format. MP4 and other formats are not supported. Convert with FFmpeg or MKVToolNix if needed.
  2. mkvpropedit must be installed and on your PATH.
  3. The matched tracklist must have at least 2 tracks with timing data. Single-track or unresolved tracklists are skipped because they provide no chapter navigation value.

CrateDigger is rate-limited by 1001Tracklists

If 1001Tracklists returns a rate-limit response, CrateDigger waits 30 seconds and retries. If the retry also fails, it stops with a message asking you to solve a captcha at 1001tracklists.com in your browser. After solving the captcha, re-run identify.

Increase the delay between files to reduce the chance of hitting rate limits: set tracklists.delay_seconds in your config (default: 5 seconds).

identify updated but enrich still shows old metadata

After re-running identify to pick up updated tracklist data, run enrich again:

cratedigger enrich ~/Music/Library/

NFO files are automatically regenerated when metadata changes, so no extra flag is needed for tags and NFOs. If you also want to rebuild posters and artwork, which use existence-only checks, add --regenerate to force those files to be overwritten as well.

organize

"--dry-run and --move cannot be used together"

These two flags are mutually exclusive. Use --dry-run first to preview what would happen, then run again with --move (without --dry-run) to actually move the files.

"not a CrateDigger library" after organize

If enrich says the folder is not a CrateDigger library, check that organize completed successfully. It creates the .cratedigger/ marker folder that enrich requires. If you pointed enrich at a subfolder rather than the library root, point it at the root instead.

Why is my set in an artist folder instead of a venue folder?

Without a places.json entry for the venue, CrateDigger has no way to recognise it as a curated place, and the set falls through the routing chain to the artist as a last resort. Add an entry to places.json for the venue (with optional aliases, color, and curated logo). After re-running cratedigger, the set routes by the venue name.

Note: if 1001Tracklists has no linked venue and no plain-text location for the set, the artist fallback is the only available routing target regardless of what is in your places.json. This is intended behavior when the tracklist page has no location data.

See Places for the file format, and 1001Tracklists integration: how venue and location data affects routing for the full routing chain.

What is the difference between a festival and a venue in CrateDigger?

Nothing structural. Both live in places.json and use the same schema: a canonical name, optional aliases, optional color, optional editions, and an optional curated logo. The distinction is conceptual: a festival is typically a recurring branded event, a venue is typically a permanent physical location. CrateDigger treats both as "places" — named entities that host DJ sets. Use the same fields for both.

See Places for examples of festivals, clubs, and venue brands side by side.

enrich

"not a CrateDigger library"

The folder you passed to enrich does not have a .cratedigger/ marker. Run organize on your library first:

cratedigger organize ~/Downloads/sets/ --output ~/Music/Library/
cratedigger enrich ~/Music/Library/

No thumbnail is produced for some files

CrateDigger tries three sources for cover art, in order:

  1. Embedded artwork in the MKV file (embedded by yt-dlp with --embed-thumbnail)
  2. A sampled video frame (requires the vision extra)
  3. A generated gradient image (always available as a last resort)

If you are getting gradient thumbnails and want actual artwork, either embed a thumbnail when downloading (see getting started: preparing your recordings) or install the vision extra:

pipx 

pipx install "cratedigger[vision] @ git+https://github.com/Rouzax/CrateDigger.git"

pip 

pip install "cratedigger[vision] @ git+https://github.com/Rouzax/CrateDigger.git"

Posters are not generated for some files

The per-video poster ({stem}-poster.jpg) requires {stem}-thumb.jpg to exist first. If you ran --only posters without running art first, no thumb exists yet. Either run the full enrich (without --only) so art runs before posters, or run them in sequence:

cratedigger enrich ~/Music/Library/ --only art
cratedigger enrich ~/Music/Library/ --only posters

Artist artwork from fanart.tv is not downloading

Fanart.tv artwork requires a MusicBrainz ID to be resolved for the artist. If fanart runs before chapter_artist_mbids, or if the artist's MBID has not been resolved yet, the lookup is skipped.

Run chapter_artist_mbids first to resolve MBIDs, then rerun enrich:

cratedigger enrich ~/Music/Library/ --only chapter_artist_mbids
cratedigger enrich ~/Music/Library/ --only fanart

If the artist still has no MBID after that, they may not be in the MusicBrainz database or the search may be returning the wrong result. Add the correct MBID to artist_mbids.json manually (~/CrateDigger/artist_mbids.json on Linux or macOS, Documents\CrateDigger\artist_mbids.json on Windows):

{
    "Artist Name": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Find the correct MBID at musicbrainz.org.

MusicBrainz IDs are not resolving for some artists

CrateDigger looks up MBIDs in this order: your override file (~/CrateDigger/artist_mbids.json on Linux or macOS, Documents\CrateDigger\artist_mbids.json on Windows), the auto cache, then a live MusicBrainz search. If an artist is not resolving:

  1. Check if the search is returning the wrong artist (a name collision). Run with --verbose to see what MusicBrainz returns.
  2. Look up the correct MBID at musicbrainz.org and add it to your override file:
{
    "Afrojack": "3abb6f9f-5b6a-4f1f-8a2d-1111111111aa"
}
  1. Rerun (no --regenerate needed):
cratedigger enrich ~/Music/Library/ --only chapter_artist_mbids,album_artist_mbids

CrateDigger detects that the resolved ID has changed and writes the update automatically.

See Configuration: artist MBID override file for details.

Add a curated logo for the place and regenerate:

  1. Find out which places are missing logos: cratedigger audit-logos ~/Music/Library/
  2. Place a logo file at the path the command suggests (for example, ~/CrateDigger/places/Tomorrowland/logo.png on Linux or macOS, Documents\CrateDigger\places\Tomorrowland\logo.png on Windows)
  3. Regenerate the folder posters:
cratedigger enrich ~/Music/Library/ --only posters --regenerate

See audit-logos and Places: curated assets for supported formats and placement paths.

fanart.tv

Fanart lookups fail or return no images

Requirements for fanart.tv lookups:

  • fanart.enabled must be true in your config (this is the default)
  • The artist must have a MusicBrainz ID resolved. Run --only chapter_artist_mbids first if MBIDs are missing.
  • A built-in project API key is included. If you are being rate-limited on large libraries, add your own personal key from fanart.tv/get-an-api-key to fanart.personal_api_key in your config.

Run with --verbose to see the lookup process and any errors.

Fanart images are stale or outdated

The fanart cache expires after the number of days configured in cache_ttl.images_days (default: 90 days, with ±20% jitter per entry). To force a fresh download for all artists, delete the artist cache folder and rerun:

rm -rf ~/.cache/CrateDigger/artists/
cratedigger enrich ~/Music/Library/ --only fanart

rm -rf ~/Library/Caches/CrateDigger/artists/
cratedigger enrich ~/Music/Library/ --only fanart

Remove-Item -Recurse "$env:LOCALAPPDATA\CrateDigger\Cache\artists"
cratedigger enrich ~/Music/Library/ --only fanart

Kodi

"Kodi sync failed: connection refused"

Kodi is not running, or the JSON-RPC web server is not enabled. Check Settings > Services > Control in Kodi and verify that Allow remote control via HTTP is on. Also confirm that the host and port in your config match.

"Kodi sync failed: 401 Unauthorized"

The username or password does not match Kodi's web server credentials. Check the kodi.username and kodi.password values in your config against the Kodi settings.

Items are not updating in Kodi after a sync

The library path that Kodi uses may not match the path CrateDigger is using. If they differ (for example, Kodi accesses the library over a network share while CrateDigger uses a local path), configure path mapping in your kodi config:

[kodi.path_mapping]
local = "/home/user/Music/Library/"
kodi = "smb://server/music/Library/"

See Kodi integration: path mapping for details.

Sync runs but nothing changes in Kodi

CrateDigger only sends a refresh for files that had actual changes in that run. If all artifacts were already up to date (skipped), no sync request is sent. Use --regenerate to force re-creation of artifacts, which will trigger a sync. Check the log file for that run to confirm whether the sync pathway fired (see Where are my logs? above).