vxcontrol/pentagi · error

ErrUsersInvalidRequest

ErrUsersInvalidRequest

Error message

group field not found

What it means

GetUsers validates the `group` query parameter against usersSQLMappers before running a grouped query. If the value is not a registered mapping key, the handler returns ErrUsersInvalidRequest with message 'group field not found', refusing to build a GROUP BY on an unknown column.

Source

Thrown at backend/pkg/server/services/users.go:353

		response.Error(c, response.ErrUsersInvalidRequest, err)
		return
	}

	uid := c.GetUint64("uid")
	privs := c.GetStringSlice("prm")
	scope := func(db *gorm.DB) *gorm.DB {
		if !slices.Contains(privs, "users.view") {
			return db.Where("id = ?", uid)
		}
		return db
	}

	query.Init("users", usersSQLMappers)

	if query.Group != "" {
		if _, ok := usersSQLMappers[query.Group]; !ok {
			logger.FromContext(c).Errorf("error finding users grouped: group field not found")
			response.Error(c, response.ErrUsersInvalidRequest, errors.New("group field not found"))
			return
		}

		var respGrouped usersGrouped
		if respGrouped.Total, err = query.QueryGrouped(s.db, &respGrouped.Grouped, scope); err != nil {
			logger.FromContext(c).WithError(err).Errorf("error finding users grouped")
			response.Error(c, response.ErrInternal, err)
			return
		}

		response.Success(c, http.StatusOK, respGrouped)
		return
	}

	if resp.Total, err = query.Query(s.db, &resp.Users, scope); err != nil {
		logger.FromContext(c).WithError(err).Errorf("error finding users")
		response.Error(c, response.ErrInternal, err)
		return

View on GitHub (pinned to ea665308ba)

Solutions

  1. Use one of the keys defined in usersSQLMappers in backend/pkg/server/services/users.go
  2. Correct the group parameter in the request
  3. Add the field to usersSQLMappers if grouped user statistics are required
  4. Regenerate/update frontend types so only valid group fields are offered

Example fix

// before
GET /api/v1/users?group=rolle
// after
GET /api/v1/users?group=role
Defensive patterns

Strategy: validation

Validate before calling

const USER_GROUPS = ['role','status','created_at']; // mirror usersSQLMappers
if (group && !USER_GROUPS.includes(group)) throw new Error(`invalid group: ${group}`);
await api.get(`/users?group=${encodeURIComponent(group)}`);

Type guard

function isUserGroupField(v: unknown): v is string {
  return typeof v === 'string' && ['role','status','created_at'].includes(v);
}

Try / catch

try {
  return await api.getUsers({ group });
} catch (e) {
  if (e.response?.data?.code === 'ErrUsersInvalidRequest') {
    console.warn(`group '${group}' rejected; defaulting to role`);
    return api.getUsers({ group: 'role' });
  }
  throw e;
}

Prevention

When it happens

Trigger: GET /users?group=<field> where <field> is missing from usersSQLMappers — typo, renamed field, or a column never whitelisted for grouping.

Common situations: Client code written against outdated docs, dashboards persisting old group params, or new user columns added without mapper registration.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/35e336eab493d579. Report an issue: GitHub.