Troubleshooting Upgrade Failures and Known Limitations in Redis Software 8.0.2 – Redis Knowledge Base

Redis Software 8.0.2 introduces new upgrade behaviors, module-handling rules, and Kubernetes operator requirements that can impact cluster availability during upgrades. This guide consolidates verified troubleshooting procedures from Support, known product limitations, and common upgrade failure patterns seen in production environments.

It covers Supported Upgrade Paths and Prerequisites, Troubleshooting Upgrade Failures, Known Limitations and Breaking Changes, Quick Reference Fixes, and Post-Remediation Validation.

Quick Fix Table

Issue	Fast Check	Immediate Action
Upgrade hangs	Any `running_actions`?	Wait or clear actions; retry upgrade.
CRDB FeatureSet errors	Mixed RS versions?	Upgrade all clusters, rerun FeatureSet update.
Custom modules present	RedisGraph / Gears?	Remove unsupported modules before upgrading.
“OLD REDIS VERSION”	Cosmetic in early builds?	Verify actual version; upgrade to 8.0.2-28+.
PATH missing	`/opt/redislabs/bin` absent?	Add to PATH and restart `rlec_supervisor`.
TLS issues	CA chain or SAN mismatch?	Replace full CA chain; validate hostname.

Supported Upgrade Paths and Prerequisites

Requirement	Description
Supported Upgrade Path	Direct upgrades are supported only between consecutive major versions (for example, 7.4.2-2 → 8.0.2-2). Skipping major versions is not supported.
Kubernetes Operator	Only Operator 7.4.2-2 or later supports upgrades to 8.0.2-2.
Database Compatibility	Databases must run supported Redis versions (6.2, 7.2, 7.4, 8.0, 8.2).
Cluster Health	Run `rladmin status extra all` and `rladmin cluster running_actions` to confirm all shards are healthy and no actions are in progress.
Primary Node Upgrade	Always upgrade the primary node first to prevent cluster hangs.
Review Release Notes	Review the RS 8.0.2-17 Release Notes for changes, limitations, and build-level fixes.

Troubleshooting Upgrade Failures

General Workflow

Confirm Upgrade Path
Ensure no major versions are skipped.
For Kubernetes, verify the Operator is ≥ 7.4.2-2.
Validate Cluster Health
- Run rladmin status extra all
- Resolve any “Error” or “Degraded” states
- Confirm rladmin cluster running_actions shows no pending tasks
Review Logs
Inspect:
- /var/opt/redislabs/log/cluster_wd.log
- /var/opt/redislabs/log/supervisord.log
- redis-<ID>.log

Database Upgrade Issues

Issue	Behavior	Action
“OK, OLD REDIS VERSION” appears after upgrade	`rladmin status` shows older version	Cosmetic in certain builds (RED-171837). Confirm real version using `rladmin status databases extra all`. Upgrading to 8.0.2-28+ removes this message.

CRDB FeatureSet Upgrade Failures

Symptoms

bad_featureset_version
OLD CRDB FEATURESET VERSION

Cause

Not all participating clusters are running the same RS 8.0.2 build.

Fix

Upgrade all CRDB sites to the same RS 8.0.2 build.
Rerun: crdb-cli crdb update --crdb-guid <guid> --update-db-config-modules true

Module Handling During Upgrade

Behavior	Guidance
Built-in modules auto-enable on upgrade (JSON, Search, TS, Bloom).	Expected behavior.
Custom modules (RedisGraph, RedisGears v2) are not supported in RS 8.0.2.	Remove them prior to upgrade or upgrade will stall.
CRDB deployments require post-upgrade module sync.	Run the FeatureSet update command shown above.

Kubernetes-Specific Checks

Check	Action
Operator / REC / REDB versions	Ensure Operator ≥ 7.4.2-2 and CRDs are upgraded.
Pods stuck in Terminating or CrashLoopBackOff	Inspect Operator logs; check PVC capacity; confirm no cluster actions running.
Stalled REC upgrade	Verify storage class, Operator permissions, and that modules are supported.

Common Error Patterns and Fixes

Issue	Symptoms	Resolution
Database upgrade stuck: “OK, OLD REDIS VERSION”	Legacy version appears in `rladmin status`	Cosmetic. Validate actual DB version; upgrade to 8.0.2-28+.
CRDB FeatureSet update fails	`bad_featureset_version`	Upgrade all clusters; rerun module update.
Rolling upgrade stuck with custom modules	Node addition fails	Remove unsupported modules.
Invalid module configuration	“unknown config option”	Remove invalid config using `ccs-cli` before upgrading.
PATH missing after upgrade	Redis CLI commands not found	Add `/opt/redislabs/bin` to PATH in `/etc/opt/redislabs/redislabs_env_config.sh`, restart `rlec_supervisor`.
TLS handshake failures	Connection refused or cert errors	Validate full CA chain and SANs; see Redis KB TLS Troubleshooting Guide.
K8s Operator upgrade freezes	REC/REDB stuck	Confirm Operator version, CRDs, and storage prerequisites.
Pods restart repeatedly	CrashLoopBackOff	Check node resources, PVC saturation, unresolved cluster actions.
License rejected	“license rejected” appears	Upload renewed license matching cluster FQDN.

Known Limitations and Breaking Changes

Limitation / Behavior	Impact	Guidance
Custom Modules unsupported	Upgrade stalls or nodes fail to join	Remove RedisGraph, RedisGears v2, or any custom module prior to upgrade.
Rolling upgrade w/ custom modules	Can hang cluster	Clean module list before upgrading.
Active-Active (CRDB) module commands unavailable until all sites upgraded	CRDB operations partially unavailable	Upgrade all sites first, then update FeatureSet.
Redis 8.0 Flash support not available	Flash-enabled DBs cannot run 8.0	Use Redis 8.2 (Flex v2).
ACL categories not active	Reduced ACL granularity	Use explicit per-command permissions.
Legacy UI options removed	Some actions unavailable in UI	Use REST API or CLI equivalents.
K8s Operator restrictions	Custom modules & INE cert uploads unsupported	Use default Operator TLS.
OS deprecations (RHEL 7, Ubuntu 18.04)	Installer blocks	Migrate to supported OS versions.
Memory usage spike in 8.0.2-25	Elevated RSS due to jemalloc	Upgrade to 8.0.2-28+.
Binary downgrade unsupported	Cannot roll back binaries	Use backup-restore rollback only.

Quick Reference: Common Issues and Fixes

Issue	Root Cause	Resolution
Upgrade hangs on node join	Version mismatch or pending cluster action	Ensure all nodes run 8.0.2 and clear `running_actions`.
CRDB sync failure	Mixed FeatureSet version	Upgrade all sites, then re-sync modules.
“Buffer too small for dataset”	Insufficient replica buffer	Increase buffer prior to upgrade.
PATH variable missing	Env file not applied	Add `/opt/redislabs/bin` and restart supervisor.
TLS/cert mismatch	Wrong SAN or expired CA	Re-upload full chain; validate SANs.
High memory usage	jemalloc regression	Upgrade to 8.0.2-28+.

Validate the Cluster After Fixes

Validation Task	Expected Result
`rladmin status extra all`	All nodes OK; no running actions.
`rladmin info`	Reports RS 8.0.2-17 or later build.
Database status	All DBs active and healthy.
Cluster Manager UI	No red alerts; cluster fully functional.
Client connections	Successful authentication and command execution.
Monitoring tools	Prometheus / Datadog dashboards collecting metrics normally.

Related to