goharbor/harbor · error · ErrorGroupNotExist

group does not exist

Error message

group does not exist

What it means

Sentinel error ErrorGroupNotExist is returned by auth.SearchAndOnBoardGroup when the auth backend's SearchGroup succeeds but yields nil - the group key (for LDAP, the group DN; for auth proxy, the group name) resolved to no known group. It surfaces during login/onboarding of group-based users.

Source

Thrown at src/core/auth/authenticator.go:41

	"github.com/goharbor/harbor/src/common"
	"github.com/goharbor/harbor/src/common/models"
	"github.com/goharbor/harbor/src/lib/config"
	libErrors "github.com/goharbor/harbor/src/lib/errors"
	"github.com/goharbor/harbor/src/lib/log"
	"github.com/goharbor/harbor/src/pkg/user"
	"github.com/goharbor/harbor/src/pkg/usergroup/model"
)

// 1.5 seconds
const frozenTime time.Duration = 1500 * time.Millisecond

var lock = NewUserLock(frozenTime)

// ErrorUserNotExist ...
var ErrorUserNotExist = errors.New("user does not exist")

// ErrorGroupNotExist ...
var ErrorGroupNotExist = errors.New("group does not exist")

// ErrDuplicateLDAPGroup ...
var ErrDuplicateLDAPGroup = errors.New("a LDAP user group with same DN already exist")

// ErrInvalidLDAPGroupDN ...
var ErrInvalidLDAPGroupDN = errors.New("the LDAP group DN is invalid")

// ErrNotSupported ...
var ErrNotSupported = errors.New("not supported")

// ErrAuth is the type of error to indicate a failed authentication due to user's error.
type ErrAuth struct {
	details string
}

// Error ...
func (ea ErrAuth) Error() string {
	return fmt.Sprintf("Failed to authenticate user, due to error '%s'", ea.details)

View on GitHub (pinned to 7b2fd08cc5)

Solutions

  1. Verify the group still exists in LDAP/AD and lies inside the configured group base DN and GroupSearchFilter
  2. For auth proxy, confirm the group header carries the exact current group name
  3. Re-save the LDAP auth settings after directory changes so Harbor re-syncs groups
  4. If the group was recreated, update Harbor user groups to the new DN
Defensive patterns

Strategy: try-catch

Type guard

func isGroupNotExist(err error) bool { return errors.Is(err, auth.ErrorGroupNotExist) }

Try / catch

id, err := auth.SearchAndOnBoardGroup(ctx, groupDN, alt)
if err != nil {
    if errors.Is(err, auth.ErrorGroupNotExist) {
        // group vanished from directory: surface a clear message, do not retry blindly
        return fmt.Errorf("group %q not found in auth backend", groupDN)
    }
    return err
}

Prevention

When it happens

Trigger: An LDAP user logs in whose group DN is no longer found by the LDAP search; SearchAndOnBoardGroup is called with a group key that was removed from the directory; auth proxy group header value matches nothing.

Common situations: Group DN moved or deleted in AD after Harbor learned of it LDAP group base DN / group filter changed so the group falls outside the search auth proxy header delivering a stale group name.

Related errors

AI-assisted analysis of goharbor/harbor@7b2fd08cc5 (2026-08-16). Data as JSON: /api/errors/e6d242d7469dce13. Report an issue: GitHub.