Redis Search Troubleshooting

Common errors and how to resolve them when working with Upstash Redis Search.

Index Errors#

ERR Index <name> already exists#

You tried to create an index that already exists.

Fix: Use the existsOk option (SDK) or EXISTSOK flag (CLI) to skip creation if an identical index already exists:

SEARCH.CREATE products ON JSON PREFIX 1 product: EXISTSOK SCHEMA name TEXT

Or drop the existing index first with SEARCH.DROP <name>.

If the existing index has a different schema/configuration, EXISTSOK still returns an error. In that case, drop and recreate the index (or use a different index name).

Query Errors#

ERR limit should be a positive number less than 1000#

The LIMIT value must be a positive integer. Valid range is 1 to 1000 (inclusive).

Common causes:

• Using LIMIT 0 — the minimum is 1
• Using LIMIT 1001 or greater — the maximum is 1000
• Using RediSearch-style LIMIT <offset> <count> syntax — Upstash uses separate LIMIT and OFFSET keywords

Fix:

# CorrectSEARCH.QUERY products '{}' LIMIT 10 OFFSET 20# Incorrect (RediSearch style)SEARCH.QUERY products '{}' LIMIT 20 10

ERR Unknown field operator: $not#

There is no $not operator. Use $mustNot for exclusion filtering:

# CorrectSEARCH.QUERY products '{"$mustNot": [{"status": "discontinued"}]}'# IncorrectSEARCH.QUERY products '{"status": {"$not": "discontinued"}}'

Aggregation Errors#

Aggregation operator requires field to be FAST#

Aggregation '<name>' operator '$avg' requires field '<field>' to be FAST

All metric aggregation operators ($avg, $sum, $min, $max, $count, $cardinality, $stats, $extendedStats, $percentiles) require the target field to be defined as FAST in the index schema.

Fix: Recreate the index with the field marked as FAST:

# Ensure 'price' has the FAST flagSEARCH.CREATE products ON JSON PREFIX 1 product: SCHEMA name TEXT price F64 FAST

In the TypeScript SDK, numeric fields (s.number()) and keyword fields (s.keyword()) are FAST. Date and boolean fields are FAST only when you call .fast(): s.date().fast() and s.boolean().fast(). In the Python SDK, pass {"type": "F64", "fast": True}.

Missing required ‘field’ property#

Aggregation '<name>' is missing required 'field' property

Every metric aggregation operator requires a field property pointing to the field to aggregate.

Fix: Pass field as an object property, not a bare string:

Correct:

{"avg_price": {"$avg": {"field": "price"}}}

Incorrect — operator value is a bare string instead of an object:

{"avg_price": {"$avg": "price"}}

Aggregation must be a JSON object#

Aggregation '<name>' must be a JSON object

The aggregation alias must map to an object containing an operator key (like $avg), not directly to a string or number.

Fix:

Correct:

{"avg_price": {"$avg": {"field": "price"}}}

Incorrect — alias maps directly to an operator string:

{"avg_price": "$avg"}

Schema Errors#

Field type mismatches#

If a document field’s value doesn’t match the schema type (e.g., a string value "abc" for a numeric field), that document is silently skipped during indexing for that field. It will not appear in queries that filter on the mismatched field.

Missing document fields#

If a document doesn’t have a field defined in the schema, it simply won’t match queries filtering on that field. No error is raised.

Upstash Redis Search vs RediSearch#

Upstash Redis Search uses SEARCH.* commands and is a separate implementation from the open-source RediSearch module which uses FT.* commands. The two are not compatible.

If you are migrating from RediSearch, you will need to rewrite your queries to use the JSON filter syntax and SEARCH.* commands.