netbirdio/netbird · warning

group not found

Error message

group not found

What it means

Sentinel error returned by GroupsAPI.GetByName when the management REST API's group list, filtered by the name query parameter, comes back with zero entries. It means no group with that exact name exists in the account the API token belongs to. Matching is exact, so typos, case differences, and names owned by another account all produce it.

Source

Thrown at shared/management/client/rest/groups.go:13

package rest

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"

	"github.com/netbirdio/netbird/shared/management/http/api"
)

// ErrGroupNotFound is returned when a group is not found
var ErrGroupNotFound = errors.New("group not found")

// GroupsAPI APIs for Groups, do not use directly
type GroupsAPI struct {
	c *Client
}

// List list all groups
// See more: https://docs.netbird.io/api/resources/groups#list-all-groups
func (a *GroupsAPI) List(ctx context.Context) ([]api.Group, error) {
	resp, err := a.c.NewRequest(ctx, "GET", "/api/groups", nil, nil)
	if err != nil {
		return nil, err
	}
	if resp.Body != nil {
		defer resp.Body.Close()
	}
	ret, err := parseResponse[[]api.Group](resp)
	return ret, err

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. List all groups (Groups.List) and compare the exact name, case-sensitively
2. Create the group first with Groups.Create, or fix the name in the calling config
3. Confirm the API token belongs to the account that owns the group

Example fix

// before
group, err := restClient.Groups.GetByName(ctx, "my-group")

// after
group, err := restClient.Groups.GetByName(ctx, "my-group")
if errors.Is(err, rest.ErrGroupNotFound) {
	group, err = restClient.Groups.Create(ctx, api.PostApiGroupsJSONRequestBody{Name: "my-group"})
	if err != nil {
		return err
	}
}

groups, err := restClient.Groups.List(ctx)
if err != nil {
	return err
}
var found *api.Group
for i := range groups {
	if groups[i].Name != nil && *groups[i].Name == wantName {
		found = &groups[i]
		break
	}
}

func isGroupNotFound(err error) bool {
	return errors.Is(err, rest.ErrGroupNotFound)
}

group, err := restClient.Groups.GetByName(ctx, name)
if errors.Is(err, rest.ErrGroupNotFound) {
	// create it or fall back to a configured group ID
} else if err != nil {
	return err
}

When it happens

Trigger: rest.Groups.GetByName(ctx, name) where name is misspelled, has different case or whitespace, was deleted or renamed concurrently, or exists only in a different account than the token's.

Common situations: Automation that attaches peers to a group before creating it; service-user token scoped to the wrong account; group names read from stale config after a rename.

Related errors

• user group name cannot be empty
• at least one distribution group is required
• router not part of network
• peer and peer_groups cannot be set at the same time
• either peer or peer_groups must be provided

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/0e3206c57eb3c865. Report an issue: GitHub.