navidrome/navidrome · error

missing required parameter 'u' (username)

Error message

missing required parameter 'u' (username)

What it means

The Subsonic API requires the 'u' (username) parameter on every request. executeRequest validates its presence after parsing the URI and rejects the call if it is empty. The plugin host uses this username both for permission checks and internal authentication, so it is mandatory.

Source

Thrown at plugins/host_subsonicapi.go:65

// If setJSON is true, the 'f=json' query parameter is added.
func (s *subsonicAPIServiceImpl) executeRequest(ctx context.Context, uri string, setJSON bool) (*httptest.ResponseRecorder, error) {
	if s.router == nil {
		return nil, fmt.Errorf("SubsonicAPI router not available")
	}

	// Parse the input URL
	parsedURL, err := url.Parse(uri)
	if err != nil {
		return nil, fmt.Errorf("invalid URL format: %w", err)
	}

	// Extract query parameters
	query := parsedURL.Query()

	// Validate that 'u' (username) parameter is present
	username := query.Get("u")
	if username == "" {
		return nil, fmt.Errorf("missing required parameter 'u' (username)")
	}

	if err := s.checkPermissions(ctx, username); err != nil {
		log.Warn(ctx, "SubsonicAPI call blocked by permissions", "plugin", s.pluginID, "user", username, err)
		return nil, err
	}

	// Add required Subsonic API parameters
	query.Set("c", s.pluginID)         // Client name (plugin ID)
	query.Set("v", subsonicAPIVersion) // API version
	if setJSON {
		query.Set("f", "json") // Response format
	}

	// Extract the endpoint from the path
	endpoint := path.Base(parsedURL.Path)

	// Build the final URL with processed path and modified query parameters

View on GitHub (pinned to 4ed7494a32)

Solutions

1. Append u=<username> to the query string before calling
2. Check that the variable supplying the username is non-empty (config not blank)
3. Use url.Values{"u": {username}, ...}.Encode() so empty values are obvious
4. Note other Subsonic params (v, c, t/s) may be added by the host; only u must come from you

Example fix

// before
resp, err := api.Call(ctx, "/rest/getPlaylists")
// after
resp, err := api.Call(ctx, "/rest/getPlaylists?u="+url.QueryEscape(username))

if username == "" {
    return errors.New("username required for Subsonic API calls")
}
uri := "/rest/getPlaylists?u=" + url.QueryEscape(username)

if err != nil {
    if strings.Contains(err.Error(), "missing required parameter 'u'") {
        return fmt.Errorf("plugin config is missing the Subsonic username")
    }
    return err
}

When it happens

Trigger: Calling subsonicAPI.Call/CallRaw with a URI whose query string lacks 'u' or has u= (empty value), e.g. '/rest/getPlaylists' or '/rest/getPlaylists?u=&v=1.16.1'.

Common situations: Copy-pasting an endpoint path without the auth parameters; template/config variable for the username left empty; forgetting to append the username when constructing the request programmatically.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• invalid URL format: %w
• no command arguments provided
• no mpv command arguments provided
• range criteria for %q must be a [min, max] pair, got: %v
• SubsonicAPI router not available

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