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("F64")) and date fields (s.date()) are FAST by default. Boolean fields (s.boolean()) are also FAST by default. If you explicitly called .fast(false), remove it.

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.