What causes "invalid term format" in go-redis/redis?

Verify you are talking to a real Redis Stack / RediSearch instance.

invalid term format

Error message

invalid term format

What it means

Returned by parseFTSpellCheck (RESP2 path) when a term entry is not a 3-element array. The RESP2 FT.SPELLCHECK format is [1, term, [[score, suggestion], ...]] per term; a malformed entry is rejected at search_commands.go:2537.

Source

Thrown at search_commands.go:2538

			}
		}

		results = append(results, SpellCheckResult{
			Term:        term,
			Suggestions: suggestions,
		})
	}

	return results, nil
}

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")
			}

View on GitHub (pinned to 36d97525cd)

Solutions

Verify you are talking to a real Redis Stack / RediSearch instance.
Upgrade RediSearch to a version whose SPELLCHECK output matches the documented RESP2 schema.
Inspect the raw reply (use RawResult) to see what the server actually returned.

Example fix

null

Defensive patterns

Strategy: try-catch

Type guard

func isTermTuple(v interface{}) bool {
    t, ok := v.([]interface{})
    return ok && len(t) == 3
}

Try / catch

res, err := client.FTSpellCheck(ctx, idx, term).Result()
if err != nil && strings.Contains(err.Error(), "invalid term format") {
    raw, _ := client.FTSpellCheck(ctx, idx, term).RawResult()
    // log raw to diagnose server/proxy issue
    _ = raw
}

Prevention

Point the client at a genuine RediSearch-enabled Redis.
Upgrade Redis Stack/RediSearch to a current release.
Use RawResult() to capture malformed replies for diagnosis.

When it happens

Trigger: A RESP2 FT.SPELLCHECK reply whose per-term element is not a []interface{} of length 3. Indicates non-standard server output or a protocol/translation issue.

Common situations: Custom Redis proxy rewriting replies, an incompatible Redis fork, or running against a non-RediSearch backend that happens to answer the command.

Related errors

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