Why can't I add or update this album? This page walks through the most common MusicBrainz-related problems in Lidarr — propagation lag, unknown release statuses, bad matches, and the cache-bust process — and helps decide whether to retry, wait, or fix data upstream.
If you're new to how Lidarr depends on MusicBrainz, read Concepts first — this page assumes you already know that MusicBrainz is the source of truth and Lidarr reads from it through a cache.
There are three caches between MusicBrainz and what you see in the UI:
musicbrainz.org.A change made at MusicBrainz is only visible in Lidarr once it has propagated through all three. That usually takes hours, sometimes longer. This is normal — most "it is on MusicBrainz but not in Lidarr" reports are propagation, not breakage.
Three likely causes, in order of how often they come up:
The edit has not reached the Servarr metadata server yet, or it has, but Lidarr has not refreshed the artist since.
unknownLidarr only imports releases with statuses it recognises. Anything with status unknown at MusicBrainz is skipped even if the release is otherwise complete.
Statuses Lidarr can import, depending on the Release Statuses selected in your metadata profile:
The fix is to update the status at MusicBrainz — typically to Official. See Updating MusicBrainz below for the tools.
The
unknownstatus is the single most common reason a release visible onmusicbrainz.orgdoes not appear in Lidarr. Check the status on the MusicBrainz release page before concluding anything is broken on the Lidarr side.
Lidarr matched the release group to one specific release (one pressing, one format) that does not include the tracks you were expecting. The data is fine; the match is wrong. See Picking the right release.
A release group on MusicBrainz usually has several releases underneath it — one per pressing, per format (CD, vinyl, digital, cassette), per region, and sometimes per edition (standard, deluxe, remastered). Lidarr tracks release groups as albums and only holds one release per album at a time. If Lidarr picked a different release than the one you have, the track list will not match.
To switch releases:
If none of the releases match what you actually have, the release itself probably does not exist at MusicBrainz yet — add it upstream rather than trying to work around it in Lidarr.
"Various Artists," soundtracks, and similar meta-artists on MusicBrainz have thousands of releases attached because the entity is effectively a catch-all. Lidarr does not add these by design — pulling in every compilation ever credited to Various Artists is the kind of bulk metadata load that punishes both the user and the metadata server.
If you want a specific compilation album, add it under the artist(s) that actually perform on it, or add the album directly and leave the artist unmonitored.
If an album is already imported and Lidarr starts searching for and grabbing it again — sometimes repeatedly, sometimes into the same folder on top of what's already there — the cause is usually upstream at MusicBrainz, not in Lidarr.
The usual trigger: someone adds a new release (a new pressing, a new format, a remaster) to MusicBrainz but creates a new release group for it instead of attaching the release to the existing release group. Because Lidarr treats each release group as an album, the new release group shows up as a distinct new album — so Lidarr monitors it and starts the grab-and-import cycle for something you already have.
Two fixes:
If you notice this pattern for a specific artist, it's worth spot-checking their MusicBrainz discography for other duplicated release groups while you are already looking — merging them in one pass is cheaper than catching each duplicate one at a time.
If an edit is more than 24 hours old, has propagated through the MusicBrainz site, and still does not show in Lidarr after a manual Refresh Artist, that is when the cache-bust process applies.
The Servarr metadata server occasionally holds onto stale data past the normal refresh window. When that happens, a Servarr Team Member or Servarr Donatarr can clear the cache for a specific artist or album.
!refresh album/<release-group-mbid> — note this is the release group MBID (what Lidarr calls the album ID), not the release MBID. Mixing these two up is the most common reason a refresh request does nothing.!refresh artist/<artist-mbid> — the artist MBID from MusicBrainz.!refresh album/96eacc6a-b618-490b-91f2-6e58b57b57aa or !refresh artist/9255f594-b912-4bdf-87a2-ada04502a459.Release ID vs. Release Group ID. MusicBrainz has two IDs that look similar but point to different things. The release group is the album (e.g. Kid A); the release is a specific pressing of it (e.g. the 2000 UK CD vs. the 2017 remaster). Lidarr treats albums as release groups — so the ID you want for
!refresh album/…is the one shown on the MusicBrainz release group page, not the individual release page.
Refresh Releases is the task that keeps Lidarr's local view of metadata in sync with the metadata server. It cannot be disabled, and it should not be disabled through database edits or other workarounds — Lidarr relies on it to catch upstream corrections (ID changes, cast updates, alt titles, ratings, summaries, translations) that affect matching and organisation.
If the refresh is causing heavy disk I/O, the setting to look at is Rescan Artist Folder after Refresh:
Always, which re-reads every file after every refresh.Manual usually solves the I/O problem — refreshes still update metadata, they just do not re-scan files on disk.Never unless every change to your library (additions, upgrades, deletions) goes through Lidarr. Manual file changes or third-party tooling will not be picked up if rescans never run.Fixes to metadata happen at MusicBrainz, not in Lidarr. Lidarr reads MusicBrainz; it does not override it.
Harmony is a music-metadata aggregator and MusicBrainz importer. For most users it is the easiest and most accurate way to add a missing release — it pulls release data from multiple upstream sources (streaming services, digital retailers, etc.), cross-references them, and produces a MusicBrainz-ready import with the key fields (album type, release status, track list) already populated. Compared to hand-editing on MusicBrainz, Harmony avoids the common mistakes (missing album type, wrong status) that cause a freshly-imported release to land as unknown and stay invisible to Lidarr.
Use Harmony when:
The MusicBrainz community maintains a set of browser userscripts that assist with editing and importing — see the MusicBrainz Userscripts guide. These are useful for bulk imports from specific sources (Bandcamp, Discogs, streaming services, etc.).
Caveat for Lidarr users. Some userscripts do not copy every field from the upstream source. The field that most often gets missed is the album type — if the imported release lands at MusicBrainz without a primary type, it shows up as
unknownand Lidarr will not add it. After any scripted import, verify the release's type on MusicBrainz before submitting, and expect to fix it manually if the script left it blank.
Direct edits on musicbrainz.org are the right path for:
unknown to OfficialAll edits go through a review window — usually a few days for the change to become visible site-wide, then the additional propagation time through the metadata server and Lidarr on top of that. Start the clock as soon as the edit is submitted; do not wait until it is visible on MusicBrainz to start counting.
Picard is a tagging application that reads files, identifies releases, and tags against MusicBrainz IDs. For users already tagging a library, Picard is the right tool to keep files in sync with MusicBrainz once the data there is correct — clean tags also improve matching on import (see Importing an Existing Library).
Picard is a tagging tool first and foremost. For adding or editing releases at MusicBrainz, reach for Harmony or the web editor instead.
Cover art is not pulled directly by Lidarr — covers are served to Lidarr via the Servarr metadata server, which aggregates from upstream sources. The canonical place to upload album art is the Cover Art Archive (attached to the MusicBrainz release), but don't expect an instant appearance in Lidarr:
This page does not cover MusicBrainz's style guidelines or the review process. If you have never edited MusicBrainz before, start with How to Contribute on the MusicBrainz wiki.
When Lidarr processes a Spotify import list, it resolves each Spotify track or album ID to a MusicBrainz ID in two stages:
When you hit the rate limit, affected albums will not be added to Lidarr's queue until the limit clears.
Resolution:
To add a Spotify relationship on MusicBrainz: open the release, go to Edit → Add Relationship, set the type to stream for free (Spotify) or the appropriate streaming relationship type, and paste the Spotify album URL. The cache will pick it up on the next metadata server refresh cycle.
A 429 from Spotify does not indicate anything wrong with your Lidarr setup — it is a server-side rate limit on lookups. Checking Lidarr's logs at Debug level will show the 429 responses if you want to confirm that is the cause.
| Situation | Action |
|---|---|
| You just submitted an edit at MusicBrainz | Wait ~24 hours, then Refresh Artist in Lidarr |
| You just uploaded cover art to the Cover Art Archive | Allow days, not hours — covers propagate slower than metadata |
A release status was unknown and you changed it |
Wait ~24 hours after the edit is visible on MusicBrainz, then Refresh Artist |
| A scripted import left the album type blank | Fix the type on MusicBrainz first; the release is invisible to Lidarr until then |
| Lidarr matched the wrong release | Use the release dropdown on the album detail page — no waiting needed |
| You already waited 24+ hours and refreshed and the data is still wrong | Request a cache-bust on the Servarr Discord with !refresh album/<release-group-mbid> or !refresh artist/<artist-mbid> |
| The release does not exist on MusicBrainz at all | Add it with Harmony or the MusicBrainz web editor, then follow the first row above |