goharbor/harbor · warning

should provide a group name

Error message

should provide a group name

What it means

Auth-proxy OnBoardGroup rejects a model.UserGroup whose GroupName is empty before touching the database. It means a group association was detected for the HTTP-authenticated user, but the group name Harbor derived (from the configured group header) is blank, so there is nothing to onboard.

Source

Thrown at src/core/auth/authproxy/auth.go:197

	if err != nil {
		log.Warningf("Failed to refresh configuration for HTTP Auth Proxy Authenticator, error: %v, the default settings will be used", err)
	}
	var ug *model.UserGroup
	if a.SkipSearch {
		ug = &model.UserGroup{
			GroupName: groupKey,
			GroupType: common.HTTPGroupType,
		}
		return ug, nil
	}
	return nil, nil
}

// OnBoardGroup create user group entity in Harbor DB, altGroupName is not used.
func (a *Auth) OnBoardGroup(ctx context.Context, u *model.UserGroup, _ string) error {
	// if group name provided, on board the user group
	if len(u.GroupName) == 0 {
		return errors.New("should provide a group name")
	}
	u.GroupType = common.HTTPGroupType
	err := usergroup.Ctl.Ensure(ctx, u)
	if err != nil {
		return err
	}
	return nil
}

func (a *Auth) fillInModel(u *models.User) error {
	if strings.TrimSpace(u.Username) == "" {
		return fmt.Errorf("username cannot be empty")
	}
	u.Realname = u.Username
	u.Password = "1234567ab"
	u.Comment = userEntryComment
	if strings.Contains(u.Username, "@") {
		u.Email = u.Username

View on GitHub (pinned to 7b2fd08cc5)

Solutions

1. Verify the group header (e.g. X-Remote-Group) sends a non-empty value for this user
2. Fix the reverse proxy / IdP to emit the real group name
3. If the user has no group, omit the header entirely - empty values are rejected, not skipped

// On the proxy side, never forward an empty group header
g := strings.TrimSpace(r.Header.Get("X-Remote-Group"))
if g == "" {
    r.Header.Del("X-Remote-Group") // absent instead of empty
}

func isEmptyGroupErr(err error) bool { return err != nil && strings.Contains(err.Error(), "should provide a group name") }

if err := auth.OnBoardGroup(ctx, ug, ""); err != nil {
    if strings.Contains(err.Error(), "should provide a group name") {
        // upstream header empty: alert IdP/proxy config, do not retry
    }
}

When it happens

Trigger: Login via auth proxy where the group header is present but its value is empty (e.g. 'X-Remote-Group:'), or the derived group list contains an empty element.

Common situations: Reverse proxy strips the header value for certain users group header name misconfigured so an empty value leaks through upstream identity provider returns an empty group entry.

Related errors

• the LDAP group DN is invalid
• File {} not exist
• Internal dir for tls {} not exist
• Port number in metrics is not valid
• Jaeger Colector Endpoint or Agent host not set, must set one

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