What causes "invalid document fields format" in go-redis/redis?

Check that NoContent is false only when you really expect field arrays.

invalid document fields format

Error message

invalid document fields format

What it means

Returned in parseFTSearch (search_commands.go:2660-2668): after the doc ID (and optional score/payload/sortkey), the next element must be either an array of field pairs, nil/RESP nil, or it errors here. A scalar (string, int) where the fields array is expected trips this.

Source

Thrown at search_commands.go:2667

			}
		}

		if withSortKeys && i < len(data) {
			if sortKey, ok := data[i].(string); ok {
				doc.SortKey = &sortKey
				i++
			}
		}

		if i < len(data) {
			fields, ok := data[i].([]interface{})
			if !ok {
				if data[i] == proto.Nil || data[i] == nil {
					doc.Error = proto.Nil
					doc.Fields = map[string]string{}
					fields = []interface{}{}
				} else {
					return FTSearchResult{}, fmt.Errorf("invalid document fields format")
				}
			}

			for j := 0; j < len(fields); j += 2 {
				key, ok := fields[j].(string)
				if !ok {
					return FTSearchResult{}, fmt.Errorf("invalid field key format")
				}
				value, ok := fields[j+1].(string)
				if !ok {
					return FTSearchResult{}, fmt.Errorf("invalid field value format")
				}
				doc.Fields[key] = value
			}
			i++
		}

		results = append(results, doc)

View on GitHub (pinned to 36d97525cd)

Solutions

Check that NoContent is false only when you really expect field arrays.
Inspect RawResult() to see the element at the failing index.
Re-run via redis-cli to see canonical shape.
Upgrade Redis Stack and go-redis to remove any parser drift.

Example fix

// before — server returned IDs only but NoContent was left false
res, err := client.FTSearchWithArgs(ctx, idx, q, &redis.FTSearchOptions{}).Result()
// after — set NoContent when fields are not expected
res, err := client.FTSearchWithArgs(ctx, idx, q, &redis.FTSearchOptions{NoContent: true}).Result()

Defensive patterns

Strategy: validation

Validate before calling

// Set NoContent when you do not need field arrays, so the parser skips the fields slot.
if !needFields {
    opts.NoContent = true
}

Try / catch

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

Prevention

Set NoContent when fields are not required.
Inspect RawResult() for the failing element.
Keep RETURN/LOAD clauses consistent with the schema.

When it happens

Trigger: Reply shape mismatch — e.g. NOCONTENT was not set on the client but the server omitted fields, or an alternate reply mode (LOAD/RETURN) collapsed fields into a scalar.

Common situations: Mismatched NoContent between request and server, RETURN reducing fields unexpectedly, or a malformed reply from a proxy.

Related errors

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