go-redis/redis · error

invalid suggestions format

Error message

invalid suggestions format

What it means

Returned by parseFTSpellCheck (RESP2 path) when the third element of a term entry (the suggestions list) is not a []interface{}. Each term tuple is [1, term, [[score, suggestion], ...]]; the third slot must be an array. Guard at search_commands.go:2546.

Source

Thrown at search_commands.go:2548

}

func parseFTSpellCheck(data []interface{}) ([]SpellCheckResult, error) {
	results := make([]SpellCheckResult, 0, len(data))

	for _, termData := range data {
		termInfo, ok := termData.([]interface{})
		if !ok || len(termInfo) != 3 {
			return nil, fmt.Errorf("invalid term format")
		}

		term, ok := termInfo[1].(string)
		if !ok {
			return nil, fmt.Errorf("invalid term format")
		}

		suggestionsData, ok := termInfo[2].([]interface{})
		if !ok {
			return nil, fmt.Errorf("invalid suggestions format")
		}

		suggestions := make([]SpellCheckSuggestion, 0, len(suggestionsData))
		for _, suggestionData := range suggestionsData {
			suggestionInfo, ok := suggestionData.([]interface{})
			if !ok || len(suggestionInfo) != 2 {
				return nil, fmt.Errorf("invalid suggestion format")
			}

			scoreStr, ok := suggestionInfo[0].(string)
			if !ok {
				return nil, fmt.Errorf("invalid suggestion score format")
			}
			score, err := strconv.ParseFloat(scoreStr, 64)
			if err != nil {
				return nil, fmt.Errorf("invalid suggestion score value")
			}

View on GitHub (pinned to 36d97525cd)

Solutions

  1. Upgrade RediSearch so empty-suggestion terms still emit an empty array.
  2. Use cmd.RawResult() to inspect the raw structure if it recurs.
  3. File a RediSearch issue if a genuine server returns a non-array for the suggestions slot.

Example fix

null
Defensive patterns

Strategy: try-catch

Type guard

func suggestionsIsSlice(v interface{}) bool { _, ok := v.([]interface{}); return ok }

Try / catch

if err != nil && strings.Contains(err.Error(), "invalid suggestions format") {
    // use RawResult to inspect the suggestions slot
}

Prevention

When it happens

Trigger: A RESP2 FT.SPELLCHECK reply where the suggestions slot is a scalar/nil/map instead of an array. Happens when a term has no suggestions and the server omits the array rather than sending an empty one.

Common situations: Server-version differences in how zero-suggestion terms are serialized, or proxy mangling.

Related errors

AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06). Data as JSON: /data/errors/eceeb0dc943de678.json. Report an issue: GitHub.