What causes "wrong field for grouping" in vxcontrol/pentagi?

Use only field names present in the table's sqlMappers as the group value (e.g. for agentlogs: id, initiator, executor, task, result, flow_id, task_id, subtask_id, created_at).

vxcontrol/pentagi · error

Internal

Internal

Error message

wrong field for grouping

What it means

TableQuery.Init validates the query's Group parameter by looking it up in the table's sqlMappers and asserting the mapped value is a plain string (a SQL column expression). Grouping can only be done on a real column/expression, not on a mapper that holds a function (e.g. a custom search projection like the 'data' concatenation mapper). If the group name is unknown or maps to a non-string value, Init returns this sentinel error and the query is rejected before touching the database.

Source

Thrown at backend/pkg/server/rdb/table.go:94

		switch t := v.(type) {
		case string:
			t = q.DoConditionFormat(t)
			if isNumbericField(k) {
				q.sqlMappers[k] = t
			} else {
				q.sqlMappers[k] = "LOWER(" + t + "::text)"
			}
		case func(q *TableQuery, db *gorm.DB, value any) *gorm.DB:
			q.sqlMappers[k] = t
		default:
			continue
		}
	}
	if q.Group != "" {
		var ok bool
		q.groupField, ok = q.sqlMappers[q.Group].(string)
		if !ok {
			return errors.New("wrong field for grouping")
		}
	}
	return nil
}

// DoConditionFormat is auxiliary function to prepare condition to the table
func (q *TableQuery) DoConditionFormat(cond string) string {
	cond = strings.ReplaceAll(cond, "{{type}}", q.Type)
	cond = strings.ReplaceAll(cond, "{{table}}", q.table)
	cond = strings.ReplaceAll(cond, "{{page}}", strconv.Itoa(q.Page))
	cond = strings.ReplaceAll(cond, "{{size}}", strconv.Itoa(q.Size))
	return cond
}

// SetFilters is function to set custom filters to build target SQL query
func (q *TableQuery) SetFilters(sqlFilters []func(*gorm.DB) *gorm.DB) {
	q.sqlFilters = sqlFilters
}

View on GitHub (pinned to ea665308ba)

Solutions

Use only field names present in the table's sqlMappers as the group value (e.g. for agentlogs: id, initiator, executor, task, result, flow_id, task_id, subtask_id, created_at).
If a new groupable field is needed, add it to the sqlMappers map as a plain string SQL expression (e.g. "{{table}}.my_column"), not a func.
Remove or fix the group query parameter in the client request; fall back to no grouping.
Check that the mapper value's type is string — grouping on function-based mappers is unsupported by design.

Example fix

// before
GET /agentlogs?group=data        // 'data' mapper is a concat expression or func -> fails
// after
GET /agentlogs?group=task        // string column mapper -> Init succeeds

Defensive patterns

Strategy: validation

Validate before calling

const allowedGroups = ["id","initiator","executor","task","result","flow_id","task_id","subtask_id","created_at"];
function isGroupValid(g) { return !g || allowedGroups.includes(g); }
if (!isGroupValid(params.group)) throw new Error(`group must be one of: ${allowedGroups.join(", ")}`);

Type guard

function isStringMapper(v) { return typeof v === "string"; }

Try / catch

try {
  if err := query.Init(table, mappers); err != nil {
    if err.Error() == "wrong field for grouping" { return http.StatusBadRequest }
    return http.StatusInternalServerError
  }
} catch (/wrong field for grouping/) { /* fix group param */ }

Prevention

Derive the group dropdown in the UI from the same mapper list the backend uses.
Always call Init before using a TableQuery.
Add a unit test asserting every groupable mapper value is a string.
Never forward raw user query params into Group without whitelisting.

When it happens

Trigger: Calling a list endpoint (e.g. ListDocuments / GET with rdb.TableQuery query params) with ?group=<name> where <name> is either not a key in the table's sqlMappers map, or maps to a func/complex value instead of a SQL string expression.

Common situations: Frontend sends a group field that was renamed or removed from the backend mapper map; user passes an arbitrary JSON/query field name; developer added a mapper entry as a function and someone tries to group by it; typos like 'flowID' vs 'flow_id'.

Related errors

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