What causes "invalid results format: expected map, got %T" in go-redis/redis?

invalid results format: expected map, got %T

Error message

invalid results format: expected map, got %T

What it means

Returned by parseFTSpellCheckRESP3 when the top-level "results" entry is not itself a map[interface{}]interface{}. RediSearch RESP3 spellcheck wraps per-term suggestion lists under a results map; a non-map value means the shape diverged. The guard is at search_commands.go:2471.

Source

Thrown at search_commands.go:2473

//	  "results": map{
//	    "misspelled_term": [
//	      map{"suggestion": score},
//	      ...
//	    ],
//	    ...
//	  }
//	}
func parseFTSpellCheckRESP3(data map[interface{}]interface{}) ([]SpellCheckResult, error) {
	results := make([]SpellCheckResult, 0)

	resultsData, ok := data["results"]
	if !ok {
		return results, nil
	}

	resultsMap, ok := resultsData.(map[interface{}]interface{})
	if !ok {
		return nil, fmt.Errorf("invalid results format: expected map, got %T", resultsData)
	}

	for termKey, suggestionsData := range resultsMap {
		term, ok := termKey.(string)
		if !ok {
			continue
		}

		suggestionsArray, ok := suggestionsData.([]interface{})
		if !ok {
			continue
		}

		suggestions := make([]SpellCheckSuggestion, 0, len(suggestionsArray))
		for _, suggestionData := range suggestionsArray {
			suggestionMap, ok := suggestionData.(map[interface{}]interface{})
			if !ok {
				continue

View on GitHub (pinned to 36d97525cd)

Solutions

Use RESP2 (Protocol: 2) to get the array-based spellcheck format this client also supports.
Upgrade RediSearch/Redis Stack to match the client's expected RESP3 schema.
If the index doesn't exist or the term has no results, ensure the server still returns a well-formed results map.

Example fix

// before
client := redis.NewClient(&redis.Options{Addr: addr, Protocol: 3})
client.FTSpellCheck(ctx, "idx", term)

// after
client := redis.NewClient(&redis.Options{Addr: addr /* RESP2 */})
client.FTSpellCheck(ctx, "idx", term)

Defensive patterns

Strategy: try-catch

Validate before calling

// Use RESP2 to get the array-based spellcheck format this client robustly supports.

Try / catch

res, err := client.FTSpellCheck(ctx, idx, term).Result()
if err != nil && strings.Contains(err.Error(), "invalid results format") {
    // switch to RESP2 client or upgrade RediSearch, then retry
}

Prevention

Match go-redis and RediSearch versions for RESP3 schema compatibility.
Falls back to RESP2 spellcheck when RESP3 shape is uncertain.
Inspect RawResult when the parser rejects the shape.

When it happens

Trigger: A RESP3 FT.SPELLCHECK reply whose "results" value is an array, scalar, or nil rather than a map. Typically server-version or module-output drift.

Common situations: Mixing a newer go-redis client with an older RediSearch whose RESP3 spellcheck schema differs, or a server that returns an empty/non-map payload on certain error states.

Related errors

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