redis: FT.AGGREGATE COLLECT: empty field name in SortBy

Error message

redis: FT.AGGREGATE COLLECT: empty field name in SortBy

What it means

The COLLECT step's SORTBY list must contain non-empty field names. buildCollectArgs validates each SortBy entry after stripping any leading '@'; an entry that is empty or only '@' cannot be sorted on and aborts argument construction with this error.

Source

Thrown at search_collect.go:113

			}
			args = append(args, ensureAtPrefix(f))
		}
	default:
		return nil, fmt.Errorf("redis: FT.AGGREGATE COLLECT requires FieldsAll or a non-empty Fields list")
	}

	// DISTINCT (optional, forward-compatible).
	if o.Distinct {
		args = append(args, "DISTINCT")
	}

	// SORTBY (optional). sort_narg counts each field plus its optional
	// direction token.
	if len(o.SortBy) > 0 {
		sortTokens := make([]interface{}, 0, len(o.SortBy)*2)
		for _, s := range o.SortBy {
			if strings.TrimLeft(s.FieldName, "@") == "" {
				return nil, fmt.Errorf("redis: FT.AGGREGATE COLLECT: empty field name in SortBy")
			}
			if s.Asc && s.Desc {
				return nil, fmt.Errorf("redis: FT.AGGREGATE COLLECT: ASC and DESC are mutually exclusive")
			}
			sortTokens = append(sortTokens, ensureAtPrefix(s.FieldName))
			switch {
			case s.Desc:
				sortTokens = append(sortTokens, "DESC")
			case s.Asc:
				sortTokens = append(sortTokens, "ASC")
				// neither set: ASC is the server default; emit nothing.
			}
		}
		args = append(args, "SORTBY", len(sortTokens))
		args = append(args, sortTokens...)
	}

	// LIMIT (optional).

View on GitHub (pinned to c5cad058c7)

Solutions

Set FieldName to a real field name (e.g. "@price" or "price")
Filter out SortBy entries with empty FieldName before building
Validate sort configuration at load time

Example fix

// before
opts := redis.CollectOptions{SortBy: []redis.CollectSortByField{{FieldName: ""}}}
// after
opts := redis.CollectOptions{SortBy: []redis.CollectSortByField{{FieldName: "@price"}}}

Defensive patterns

Strategy: validation

Validate before calling

for _, s := range sortBy {
    if strings.TrimLeft(s.FieldName, "@") == "" {
        return fmt.Errorf("empty SortBy field name")
    }
}

Prevention

Reject empty sort keys at the API boundary
Use constants for known sort fields instead of free-form strings
Trim '@' and check non-empty for all external input

When it happens

Trigger: CollectOptions.SortBy containing an entry with FieldName set to "" or "@"; buildCollectArgs returns nil with this error while iterating the sort fields.

Common situations: Sort fields derived from request parameters where the sort key was omitted; copying option structs where FieldName was left at its zero value.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of redis/go-redis@c5cad058c7 (2026-09-01). Data as JSON: /api/errors/1a7afd41f4c2ded5. Report an issue: GitHub.