go-redis/redis · error

invalid document ID format

Error message

invalid document ID format

What it means

Thrown in parseFTSearch (search_commands.go:2618-2620) when iterating the RESP2 FT.SEARCH result array and an element expected to be a document ID is not a Go string. Each document slot must begin with a string key; a non-string (int, nil, nested array) indicates the reply is malformed or misaligned with the requested flags.

Source

Thrown at search_commands.go:2620

		val:     val,
	}
}

func parseFTSearch(data []interface{}, noContent, withScores, withPayloads, withSortKeys bool) (FTSearchResult, error) {
	if len(data) < 1 {
		return FTSearchResult{}, fmt.Errorf("unexpected search result format")
	}

	total, ok := data[0].(int64)
	if !ok {
		return FTSearchResult{}, fmt.Errorf("invalid total results format")
	}

	var results []Document
	for i := 1; i < len(data); {
		docID, ok := data[i].(string)
		if !ok {
			return FTSearchResult{}, fmt.Errorf("invalid document ID format")
		}

		doc := Document{
			ID:     docID,
			Fields: make(map[string]string),
		}
		i++

		if noContent {
			results = append(results, doc)
			continue
		}

		if withScores && i < len(data) {
			if scoreStr, ok := data[i].(string); ok {
				score, err := strconv.ParseFloat(scoreStr, 64)
				if err != nil {
					return FTSearchResult{}, fmt.Errorf("invalid score format")

View on GitHub (pinned to 36d97525cd)

Solutions

1. Confirm the FTSearchOptions flags (NoContent, WithScores, WithPayloads, WithSortKeys) match what you intend.
2. Use RawResult() to dump the full array and find the offending element index i.
3. Run the same FT.SEARCH via redis-cli to see the canonical reply.
4. Reproduce on the latest Redis Stack version to rule out a fixed parser bug.

Example fix

// before
res, err := client.FTSearchWithArgs(ctx, idx, q, &redis.FTSearchOptions{WithScores: true}).Result()
// after — verify flags line up with the query you intended
opts := &redis.FTSearchOptions{WithScores: true, NoContent: true}
res, err := client.FTSearchWithArgs(ctx, idx, q, opts).Result()

res, err := client.FTSearchWithArgs(ctx, idx, q, opts).Result()
if err != nil && strings.Contains(err.Error(), "invalid document ID format") {
    raw, _ := client.FTSearchWithArgs(ctx, idx, q, opts).RawResult()
    log.Printf("doc id slot misaligned; raw=%#v", raw)
    return err
}

When it happens

Trigger: Mismatched WITHSCORES/WITHPAYLOADS/WITHSORTKEYS flags between what the caller passed and what the server returned, so the parser reads a value where it expected an ID; or a corrupted/truncated reply.

Common situations: Server-side schema change that altered the reply layout, a fork or alternate RediSearch build emitting a different array shape, or the connection interleaved replies under pipelining.

Related errors

• invalid total results format
• invalid document fields format
• invalid field value format
• invalid item key format
• invalid synonyms format

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