From 0a55cc8cafdde9ab92aa0a207507dc2165ff1caf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Deluan=20Quint=C3=A3o?= <deluan@navidrome.org>
Date: Thu, 20 Aug 2026 22:48:26 -0400
Subject: [PATCH] docs(plugins): document how a metadata agent signals "not
 found" (#6001)

A MetadataAgent plugin reports "I have no data for this item" by returning an empty response
with a nil error. Any error it returns instead is treated as a plugin fault and retried with
backoff. That rule was not documented anywhere, so an author naturally returns an error for a
missing item, and Navidrome then retries every item the plugin's source does not cover.

This is not hypothetical: the artist-nfo-metadata plugin returned an error for every artist
without an artist.nfo, which kept those artists in the artwork retry queue for hours and
tripped the artwork circuit breaker for the plugin as a whole.

Document the rule on the capability interface, which ndpgen copies into the Go PDK, and in the
MetadataAgent section of the plugin README.
---
 plugins/README.md                        | 8 ++++++++
 plugins/capabilities/metadata_agent.go   | 3 +++
 plugins/pdk/go/metadata/metadata.go      | 3 +++
 plugins/pdk/go/metadata/metadata_stub.go | 3 +++
 4 files changed, 17 insertions(+)

diff --git a/plugins/README.md b/plugins/README.md
index b04e12bd9..7042b8c45 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -174,6 +174,14 @@ Capabilities define what your plugin can do. They're automatically detected base
 
 Provides artist and album metadata. All methods are **optional** — implement only the ones your data source supports.
 
+> **Returning "not found".** When you have no data for an item, return an empty response and no
+> error. In the Go PDK that is `return nil, nil`. Navidrome reads it as a definitive "not found"
+> and stops asking.
+>
+> Return an error only when the plugin itself failed, such as an unreachable API or a broken host
+> call. Navidrome retries failed calls with backoff. A plugin that errors on "no data" makes
+> Navidrome retry every item it has no data for.
+
 | Function                          | Input                      | Output                           | Description              |
 |-----------------------------------|----------------------------|----------------------------------|--------------------------|
 | `nd_get_artist_mbid`              | `{id, name}`               | `{mbid}`                         | Get MusicBrainz ID       |
diff --git a/plugins/capabilities/metadata_agent.go b/plugins/capabilities/metadata_agent.go
index f856562c6..72cb1622f 100644
--- a/plugins/capabilities/metadata_agent.go
+++ b/plugins/capabilities/metadata_agent.go
@@ -9,6 +9,9 @@ import "github.com/navidrome/navidrome/plugins/types"
 // Plugins implementing this capability can choose which methods to implement.
 // Each method is optional - plugins only need to provide the functionality they support.
 //
+// To say "no data for this item", return a nil response and a nil error. Return an error only when
+// the plugin itself failed, because Navidrome retries failed calls with backoff.
+//
 //nd:capability name=metadata
 type MetadataAgent interface {
 	// GetArtistMBID retrieves the MusicBrainz ID for an artist.
diff --git a/plugins/pdk/go/metadata/metadata.go b/plugins/pdk/go/metadata/metadata.go
index c561c2893..bb0ae9620 100644
--- a/plugins/pdk/go/metadata/metadata.go
+++ b/plugins/pdk/go/metadata/metadata.go
@@ -186,6 +186,9 @@ type TopSongsResponse struct {
 //
 // Plugins implementing this capability can choose which methods to implement.
 // Each method is optional - plugins only need to provide the functionality they support.
+//
+// To say "no data for this item", return a nil response and a nil error. Return an error only when
+// the plugin itself failed, because Navidrome retries failed calls with backoff.
 type Metadata interface{}
 
 // ArtistMBIDProvider provides the GetArtistMBID function.
diff --git a/plugins/pdk/go/metadata/metadata_stub.go b/plugins/pdk/go/metadata/metadata_stub.go
index e72cca103..572eba4da 100644
--- a/plugins/pdk/go/metadata/metadata_stub.go
+++ b/plugins/pdk/go/metadata/metadata_stub.go
@@ -184,6 +184,9 @@ type TopSongsResponse struct {
 //
 // Plugins implementing this capability can choose which methods to implement.
 // Each method is optional - plugins only need to provide the functionality they support.
+//
+// To say "no data for this item", return a nil response and a nil error. Return an error only when
+// the plugin itself failed, because Navidrome retries failed calls with backoff.
 type Metadata interface{}
 
 // ArtistMBIDProvider provides the GetArtistMBID function.