redis/go-redis · error

FT.AGGREGATE: Steps cannot be combined with the deprecated L

Error message

FT.AGGREGATE: Steps cannot be combined with the deprecated Load, Apply, GroupBy, SortBy and SortByMax fields

What it means

FTAggregateOptions supports two generations of API: the deprecated flat fields (Load, Apply, GroupBy, SortBy, SortByMax) and the newer Steps list. They are mutually exclusive — mixing them would produce ambiguous or duplicated pipeline clauses, so validateFTAggregateOptions rejects the combination before any args are built.

Source

Thrown at search_commands.go:691

// FTAggregate - Performs a search query on an index and applies a series of aggregate transformations to the result.
// The 'index' parameter specifies the index to search, and the 'query' parameter specifies the search query.
// For more information, please refer to the Redis documentation:
// [FT.AGGREGATE]: (https://redis.io/commands/ft.aggregate/)
func (c cmdable) FTAggregate(ctx context.Context, index string, query string) *MapStringInterfaceCmd {
	args := []interface{}{"FT.AGGREGATE", index, query}
	cmd := NewMapStringInterfaceCmd(ctx, args...)
	_ = c(ctx, cmd)
	return cmd
}

// validateFTAggregateOptions validates mutually exclusive combinations of
// FTAggregateOptions fields before any command arguments are constructed.
func validateFTAggregateOptions(options *FTAggregateOptions) error {
	if len(options.Steps) > 0 {
		if options.Load != nil || options.Apply != nil || options.GroupBy != nil ||
			options.SortBy != nil || options.SortByMax != 0 {
			return fmt.Errorf("FT.AGGREGATE: Steps cannot be combined with the deprecated Load, Apply, GroupBy, SortBy and SortByMax fields")
		}
		if options.LoadAll {
			for _, step := range options.Steps {
				if step.Load != nil {
					return fmt.Errorf("FT.AGGREGATE: LOADALL and LOAD are mutually exclusive")
				}
			}
		}
	}
	if options.LoadAll && options.Load != nil {
		return fmt.Errorf("FT.AGGREGATE: LOADALL and LOAD are mutually exclusive")
	}
	return nil
}

// appendFTAggregateStep appends the Redis command arguments for a single
// aggregation pipeline step. Each step must set exactly one of Load, Apply,
// GroupBy or SortBy.

View on GitHub (pinned to c5cad058c7)

Solutions

1. Move all deprecated fields into equivalent Steps (QueryStep, LoadStep, ApplyStep, GroupByStep, SortByStep) and zero out the old fields
2. Zero the deprecated fields when constructing Steps (Load: nil, SortByMax: 0, etc.)
3. Audit option-construction helpers so only one style is produced

Example fix

// before
opts := &redis.FTAggregateOptions{
	SortBy: &redis.FTAggregateSortBy{FieldName: "@d"},
	Steps: []redis.FTAggregateStep{{Step: "GROUPBY", ...}},
}
// after
opts := &redis.FTAggregateOptions{
	Steps: []redis.FTAggregateStep{
		{Step: "SORTBY", SortBy: ...},
		{Step: "GROUPBY", ...},
	},
}

if len(opts.Steps) > 0 && (opts.Load != nil || opts.Apply != nil || opts.GroupBy != nil || opts.SortBy != nil || opts.SortByMax != 0) {
    return fmt.Errorf("Steps cannot be combined with deprecated FTAggregateOptions fields")
}

When it happens

Trigger: Passing an FTAggregateOptions with both len(Steps) > 0 and any of Load != nil, Apply != nil, GroupBy != nil, SortBy != nil, or SortByMax != 0 to FTAggregateWithArgs.

Common situations: Migrating old code to Steps while leaving deprecated fields populated; merging two option structs built by different code paths; copy-paste adding Steps on top of legacy options.

Related errors

• FT.AGGREGATE: SortByMax must follow a SortBy step
• redis: FT.AGGREGATE COLLECT: empty field name in Fields
• redis: FT.AGGREGATE COLLECT requires FieldsAll or a non-empt
• redis: FT.AGGREGATE COLLECT: empty field name in SortBy
• redis: FT.AGGREGATE COLLECT: ASC and DESC are mutually exclu

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