redis/go-redis · error

invalid synonyms format

Error message

invalid synonyms format

What it means

In the RESP2 FTSYNUMP parse path, each odd-position element must be a []interface{} of synonym strings. If it is not a slice, the client fails with this error while building FTSynDumpResult entries.

Source

Thrown at search_commands.go:3637

		return err
	}

	// RESP2 format
	termSynonymPairs, err := rd.ReadSlice()
	if err != nil {
		return err
	}

	var results []FTSynDumpResult
	for i := 0; i < len(termSynonymPairs); i += 2 {
		term, ok := termSynonymPairs[i].(string)
		if !ok {
			return fmt.Errorf("invalid term format")
		}

		synonyms, ok := termSynonymPairs[i+1].([]interface{})
		if !ok {
			return fmt.Errorf("invalid synonyms format")
		}

		synonymList := make([]string, len(synonyms))
		for j, syn := range synonyms {
			synonym, ok := syn.(string)
			if !ok {
				return fmt.Errorf("invalid synonym format")
			}
			synonymList[j] = synonym
		}

		results = append(results, FTSynDumpResult{
			Term:     term,
			Synonyms: synonymList,
		})
	}

	cmd.val = results

View on GitHub (pinned to c5cad058c7)

Solutions

1. Ensure the reply models synonyms as a RESP array per term.
2. Switch to Protocol: 3 to use the map-based RESP3 parser.
3. Correct test fixtures so each pair is [string, []interface{}].

Example fix

// before: []interface{}{"term", "syn1"}
// after:  []interface{}{"term", []interface{}{"syn1"}}

syns, ok := pairs[i+1].([]interface{})
if !ok { /* malformed synonym-list slot */ }

res, err := client.FTSynDump(ctx, "idx").Result()
if err != nil && strings.Contains(err.Error(), "invalid synonyms format") {
    // inspect raw reply; fix mock or proxy
}

When it happens

Trigger: Reading an FTSynDump reply over RESP2 where a synonym-list position decodes to something other than []interface{} (e.g. a single string instead of an array), often from a malformed mock or shifting caused by a bad term/synonym pairing.

Common situations: Mocked FTSYNUMP responses listing synonyms as a scalar; proxy rewriting replies; index-shifted replies where a synonym lands on a term slot.

Related errors

• invalid synonym format
• odd-length key/value array of length %d
• invalid execution_time format: %v
• redis: unexpected response %#v
• redis: unexpected client info data (%s)

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