After upgrading a database to Redis Software 8, applications that use Search, JSON, or Redis Search may see new errors or unexpected query behavior. These changes occur only when the database is upgraded to a Redis 8.x feature set (8.0 or 8.2). Databases that remain on 7.4, 7.2, or 6.2 continue using the legacy Redis Search parser and do not experience these changes.
This article explains the breaking changes introduced in Redis 8, why they cause previously working queries to fail, and how to update queries, ACLs, and client libraries to restore expected behavior.
Issue
After upgrading to RS 8, previously valid queries may fail with:
ERR syntax errorERR unknown commandERR invalid argumentNOPERM this user has no permissions to run the command- Queries unexpectedly returning empty results
Cause
Redis 8 introduces the Redis Search, which enforces strict parsing, validation, and ACL handling. Queries or ACLs that were loosely interpreted in Redis 7.x may now return errors.
Breaking Changes
Key Differences from Redis 7.x
| Area | Change / Impact |
|---|---|
| Redis Search | Replaces the legacy Redis Search parser with strict validation. Unsupported commands and options now return errors. |
| Deprecated commands |
FT.ADD, FT.SAFEADD, FT.DEL, FT.GET, FT.MGET, FT.CONFIG, FT.SYNADD, FT.DROP, FT._DROPIFX are removed. |
| Deprecated query options |
FILTER, GEOFILTER, NOSTOPWORDS removed. Deprecated vector options (INITIAL_CAP, BLOCK_SIZE) and RQE configs (WORKER_THREADS, MT_MODE, etc.) now fail. |
| Dialect enforcement | Only DIALECT 2 is supported. Dialects 1, 3, and 4 will error or silently return empty results. |
| Scoring changes | Default ranking changed from TF-IDF to BM25, affecting result order. |
| ACL categories | New categories: @search, @json, @timeseries, @bloom, @cuckoo, @topk, @cms, @tdigest. Existing +@read +@write now include more commands. |
| Modules & capabilities | Search, JSON, and other modules are built-in. No manual module management. |
| Client protocol | Some clients default to RESP3 (e.g., Go-Redis v9, Lettuce v6+), which may not fully support Redis Stack commands. |
Resolution Steps
1. Identify the failing query
- Check logs for error strings such as
ERR syntax errororunknown command. - Review whether deprecated commands or options are in use.
2. Update queries for Redis 8 compatibility
Command Replacements
| Deprecated Command | Replacement in Redis 8 |
|---|---|
FT.ADD / FT.SAFEADD
|
HSET or JSON.SET (indexes auto-update) |
FT.DEL |
DEL or UNLINK
|
FT.GET / FT.MGET
|
Direct key access (HGET*, JSON.GET) |
FT.CONFIG |
CONFIG GET / CONFIG SET (supported params only) |
Example Rewrite
| Old (Redis 7.x) | New (Redis 8) |
|---|---|
FT.SEARCH idx FILTER @price > 10 |
FT.SEARCH idx "@price:[10 +inf]" DIALECT 2 |
Always include DIALECT 2 in every Search query.
3. Review and adjust ACL rules
Redis 8 introduces new ACL categories. Add @search and @json (and others as needed) for clarity and forward compatibility.
| Goal | Recommended ACL Rule |
|---|---|
| App user needs Search + JSON read/write | +@read +@write +@search +@json |
| Queries failing with NOPERM | Add the relevant categories (@search, @json, @timeseries, etc.) |
Re-test any permission-sensitive queries after updating roles.
4. Validate client library protocol settings
Some SDKs default to RESP3, which does not fully support Redis Stack commands.
| Client | Default Protocol | Recommended Setting for Redis 8 Search/JSON |
|---|---|---|
| Go-Redis v9 | RESP3 | Set protocol = RESP2 |
| Lettuce v6+ | RESP3 | Use ProtocolVersion.RESP2
|
| Others | Varies | Confirm protocol and prefer RESP2 |
5. Test queries in a staging RS 8 environment
- Run application workloads against staging before production rollout.
- Validate ranking changes and ACL behavior.
- Confirm Search, JSON, and Redis Search command compatibility.
Common Symptoms and Fixes
| Symptom | Likely Cause | Resolution |
|---|---|---|
ERR syntax error |
Deprecated syntax such as FILTER / GEOFILTER
|
Rewrite using inline numeric ranges; add DIALECT 2. |
| Empty search results | Old dialect still in query | Add DIALECT 2 to all queries. |
NOPERM errors |
Missing category such as @search or @json
|
Update ACL definitions. |
unknown command FT.CONFIG |
Command deprecated in Redis 8 | Remove or use supported CONFIG operations. |
| Search results sorted differently | Scoring changed to BM25 | Validate ordering and tune as needed. |
| Client connection or parsing errors | Client using RESP3 | Force RESP2. |
Best Practices
- Test full query workloads in staging before upgrading production clusters.
- Keep SDKs updated and configured for RESP2 when using Search/JSON.
- Monitor logs for deprecation warnings before and after upgrading.
- Review ACL rules whenever Redis introduces new command categories.
- For Active-Active DBs, avoid Search/JSON operations until all CRDB instances are upgraded to Redis 8.x.
0 comments
Please sign in to leave a comment.