# Table of Contents

- [Troubleshooting Query Failures After Upgrading to Redis Software 8 – Redis Knowledge Base](#troubleshooting-query-failures-after-upgrading-to-redis-software-8-redis-knowledge-base)

---

# Troubleshooting Query Failures After Upgrading to Redis Software 8 – Redis Knowledge Base

[Skip to main content](https://support.redislabs.com/hc/en-us/articles/31569792253970-Troubleshooting-Query-Failures-After-Upgrading-to-Redis-Software-8#main-content)

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**](https://support.redislabs.com/hc/en-us/articles/31569792253970-Troubleshooting-Query-Failures-After-Upgrading-to-Redis-Software-8#h_01KBK2YF8NNPH6APS9N8H86GZH)
, [**why they cause previously working queries to fail**](https://support.redislabs.com/hc/en-us/articles/31569792253970-Troubleshooting-Query-Failures-After-Upgrading-to-Redis-Software-8#h_01KBK2YF8NNPH6APS9N8H86GZH)
, and [**how to update queries, ACLs, and client libraries**](https://support.redislabs.com/hc/en-us/articles/31569792253970-Troubleshooting-Query-Failures-After-Upgrading-to-Redis-Software-8#h_01KBK2YF8YBX46F0GA6AAYBTE8)
 to restore expected behavior.

Issue
-----

After upgrading to RS 8, previously valid queries may fail with:

*   `ERR syntax error`
*   `ERR unknown command`
*   `ERR invalid argument`
*   `NOPERM 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 error` or `unknown 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.

Related Articles & Resources
----------------------------

*   [Redis Enterprise Software 8.0.2-17 Release Notes](https://redis.io/docs/latest/operate/rs/release-notes/rs-8-0-releases/rs-8-0-2-17/)
    
*   [Redis 8.0 Release Notes and Breaking Changes](https://redis.io/docs/latest/operate/rc/changelog/version-release-notes/8-0/)
    
*   [Search Command Deprecations and Query Parsing Changes in Redis 8](https://support.redislabs.com/hc/en-us/articles/31135349231122)
    
*   [Upgrade a Redis Enterprise Database](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-database/)
    

Related to

*   [Redis Software](https://support.redislabs.com/hc/en-us/search?content_tags=01K6X6NCRZY26AJQZ571FC2H0G&utf8=%E2%9C%93 "Search results")
    
*   [Redis Query Engine](https://support.redislabs.com/hc/en-us/search?content_tags=01KA9ER5ES46530QR48WRTC2M7&utf8=%E2%9C%93 "Search results")
    
*   [Redis 8](https://support.redislabs.com/hc/en-us/search?content_tags=01KA9ERFCYV7W8GCDHEP0G3E0W&utf8=%E2%9C%93 "Search results")
    

Related articles
----------------

*   [Monitoring Redis Software with Prometheus and Datadog](https://support.redislabs.com/hc/en-us/related/click?data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCBKJYsb0GDoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBLAQGq2HDoLbG9jYWxlSSIKZW4tdXMGOgZFVDoIdXJsSSJcL2hjL2VuLXVzL2FydGljbGVzLzI3NDM5NTc5NDMzMjM0LU1vbml0b3JpbmctUmVkaXMtU29mdHdhcmUtd2l0aC1Qcm9tZXRoZXVzLWFuZC1EYXRhZG9nBjsIVDoJcmFua2kG--4843ff008bab18a803f29d09f41e230037ea56e6)
    
*   [Upgrade Preparation for Redis Software 8.0.2](https://support.redislabs.com/hc/en-us/related/click?data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJLNt3y2HDoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBLAQGq2HDoLbG9jYWxlSSIKZW4tdXMGOgZFVDoIdXJsSSJTL2hjL2VuLXVzL2FydGljbGVzLzMxNTcwMTAyMDQ2MDk4LVVwZ3JhZGUtUHJlcGFyYXRpb24tZm9yLVJlZGlzLVNvZnR3YXJlLTgtMC0yBjsIVDoJcmFua2kH--e7d96026ff4debc18a93aa19a38f89304806a63b)
    
*   [Troubleshooting Upgrade Failures and Known Limitations in Redis Software 8.0.2](https://support.redislabs.com/hc/en-us/related/click?data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJIa5q28HDoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBLAQGq2HDoLbG9jYWxlSSIKZW4tdXMGOgZFVDoIdXJsSSJ1L2hjL2VuLXVzL2FydGljbGVzLzMxNTk2Njk2OTY3ODI2LVRyb3VibGVzaG9vdGluZy1VcGdyYWRlLUZhaWx1cmVzLWFuZC1Lbm93bi1MaW1pdGF0aW9ucy1pbi1SZWRpcy1Tb2Z0d2FyZS04LTAtMgY7CFQ6CXJhbmtpCA%3D%3D--c447990a34b74f08fc88f8f77dbe0914bf3dd59a)
    
*   [Redis Software: Search Command Deprecations and Query Parsing Changes in Redis 8](https://support.redislabs.com/hc/en-us/related/click?data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCBJObkNRHDoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBLAQGq2HDoLbG9jYWxlSSIKZW4tdXMGOgZFVDoIdXJsSSJ2L2hjL2VuLXVzL2FydGljbGVzLzMxMTM1MzQ5MjMxMTIyLVJlZGlzLVNvZnR3YXJlLVNlYXJjaC1Db21tYW5kLURlcHJlY2F0aW9ucy1hbmQtUXVlcnktUGFyc2luZy1DaGFuZ2VzLWluLVJlZGlzLTgGOwhUOglyYW5raQk%3D--f91aa07534becfffce9b89dae9293ada3d5f4d26)
    
*   [Understanding ACL Category Changes in Redis 8](https://support.redislabs.com/hc/en-us/related/click?data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCBKPuepJHToYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBLAQGq2HDoLbG9jYWxlSSIKZW4tdXMGOgZFVDoIdXJsSSJUL2hjL2VuLXVzL2FydGljbGVzLzMyMjAzMzA3ODQ3NDQyLVVuZGVyc3RhbmRpbmctQUNMLUNhdGVnb3J5LUNoYW5nZXMtaW4tUmVkaXMtOAY7CFQ6CXJhbmtpCg%3D%3D--973b7d81806bde2eea9a5397ecd5e383d0906342)
    

Please [sign in](https://redislabs.zendesk.com/access?locale=en-us&brand_id=2907276&return_to=https%3A%2F%2Fsupport.redislabs.com%2Fhc%2Fen-us%2Farticles%2F31569792253970-Troubleshooting-Query-Failures-After-Upgrading-to-Redis-Software-8)
 to leave a comment.

---