redis/go-redis · error

invalid synonym format

Error message

invalid synonym format

What it means

Within a FTSYNUMP synonym list, every element must be a string. The client fails with this error if any element of the synonym array decodes to a non-string Go value.

Source

Thrown at search_commands.go:3644

	}

	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
	return nil
}

// parseFTSynDumpRESP3 parses the RESP3 format response from FT.SYNDUMP.
// RESP3 format:
//
//	map{

View on GitHub (pinned to c5cad058c7)

Solutions

1. Fix the reply source so all synonyms are strings (RESP bulk strings).
2. Check whether a proxy or codec layer is changing element types.
3. Switch to Protocol: 3 and verify the RESP3 map path parses correctly.

Example fix

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

for _, s := range syns {
    if _, ok := s.(string); !ok { /* non-string synonym */ }
}

res, err := client.FTSynDump(ctx, "idx").Result()
if err != nil && strings.Contains(err.Error(), "invalid synonym format") {
    // inspect RawVal; correct reply source
}

When it happens

Trigger: Reading an FTSynDump reply over RESP2 where a synonym array contains a non-string element (numbers, nested arrays), typically from a malformed mock or an intermediary altering element types.

Common situations: Hand-written test fixtures with wrong synonym types; RESP proxies that encode synonyms as bulk integers; server plugin anomalies.

Related errors

• invalid synonyms 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/f6b007019f6c23b2. Report an issue: GitHub.