navidrome/navidrome · error

plugins folder not configured

Error message

plugins folder not configured

What it means

RescanPlugins returns this when the server configuration key Server.Plugins.Folder is empty. The rescan needs a filesystem folder to walk; without one there is nothing to synchronize. It is a configuration error thrown before any I/O.

Source

Thrown at plugins/manager.go:463

// UpdatePluginLibraries updates the libraries permission settings for a plugin.
// If the plugin is enabled, it will be reloaded with the new settings.
// If the plugin requires library permission and no libraries are configured (and allLibraries is false),
// the plugin will be automatically disabled.
func (m *Manager) UpdatePluginLibraries(ctx context.Context, id, librariesJSON string, allLibraries, allowWriteAccess bool) error {
	return m.updatePluginSettings(ctx, id, func(p *model.Plugin) {
		p.Libraries = librariesJSON
		p.AllLibraries = allLibraries
		p.AllowWriteAccess = allowWriteAccess
	})
}

// RescanPlugins triggers a manual rescan of the plugins folder.
// This synchronizes the database with the filesystem, discovering new plugins,
// updating changed ones, and removing deleted ones.
func (m *Manager) RescanPlugins(ctx context.Context) error {
	folder := conf.Server.Plugins.Folder.String()
	if folder == "" {
		return fmt.Errorf("plugins folder not configured")
	}
	log.Info(ctx, "Manual plugin rescan requested", "folder", folder)
	return m.syncPlugins(ctx, folder)
}

// updatePluginSettings is a common implementation for updating plugin settings.
// The updateFn is called to apply the specific field updates to the plugin.
// If the plugin is enabled, it will be reloaded. If users permission is required
// but no longer satisfied, the plugin will be disabled.
func (m *Manager) updatePluginSettings(ctx context.Context, id string, updateFn func(*model.Plugin)) error {
	if m.ds == nil {
		return fmt.Errorf("datastore not configured")
	}

	adminCtx := adminContext(ctx)
	repo := m.ds.Plugin(adminCtx)

	plugin, err := repo.Get(id)

View on GitHub (pinned to 4ed7494a32)

Solutions

1. Set the plugins folder in the server config (e.g. Plugins.Folder in the config file or corresponding env var) and restart.
2. Verify the effective config value is non-empty at runtime before calling RescanPlugins.
3. If plugins are not used, do not call RescanPlugins.

Example fix

// before: rescan with unconfigured folder
err := manager.RescanPlugins(ctx)
// after: pre-check
folder := conf.Server.Plugins.Folder.String()
if folder == "" {
    return fmt.Errorf("cannot rescan: plugins folder not configured")
}
err := manager.RescanPlugins(ctx)

if conf.Server.Plugins.Folder.String() == "" {
    return fmt.Errorf("cannot rescan: plugins folder is not configured")
}

err := manager.RescanPlugins(ctx)
if err != nil && err.Error() == "plugins folder not configured" {
    log.Warn("plugin rescan skipped: no folder configured")
    return nil
}

When it happens

Trigger: Calling RescanPlugins(ctx) on a server where the plugins folder config option was never set (or set to "").

Common situations: Fresh installs where plugin support was never configured; deployments overriding config files with partial env/flags that omit the plugins folder; tests running with default config.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• datastore not configured
• SubsonicAPI router not available
• no users configured for plugin %s
• getting plugin from DB: %w
• loading plugin: %w

AI-assisted analysis of navidrome/navidrome@4ed7494a32 (2026-09-01). Data as JSON: /api/errors/43ad3aa9fc03beb1. Report an issue: GitHub.