Common Tair connection errors and solutions-Tair (Redis® OSS-Compatible)(Tair)-阿里云帮助中心

Error overview

Category	Error item
General Redis exceptions	ERR illegal address ERR sentinel compatibility mode is disabled ERR max number of clients reached NOAUTH Authentication required WRONGPASS invalid username-password pair ERR invalid password Connection reset by peer UnknownHostException OOM command not allowed when used memory > 'maxmemory' WRONGTYPE Operation against a key holding the wrong kind of value ERR unknown command 'xxx' ERR command 'xxx' not supported for your account NOPERM this user has no permissions to run the 'xxx' ERR FLUSHDB is not allowed in migrating mode CROSSSLOT Keys in request don't hash to the same slot ERR READONLY you can't write against a read-only instance Failed to connect to any host resolved for DNS name
redis-cli	Connection reset by peer ERR must use an SSL connection on the SSL port
General proxy mode exceptions	ERR client IP is not in the whitelist NOWRITE You can't write against a read-only Redis instance ERR syntax error ERR no such db node ERR 'xxx' command keys must be in the same slot ERR for redis cluster, eval/evalsha number of keys can't be negative or zero ERR request refused, too many pending requests, now count xxx, beyond threshold xxx ERR redis temporary failure ERR redis temporary failure (ErrorCode 7002)
Lua scripts and transactions	NOSCRIPT No matching script. Please use EVAL. BUSY Redis is busy running a script. You can only call SCRIPT KILL or SHUTDOWN NOSAVE. ERR command eval not supported for normal user ERR eval/evalsha command keys must be in the same slot ERR bad Lua script for redis cluster, all the keys that the script uses should be passed using the KEYS array EXECABORT Transaction discarded because of previous errors UNKILLABLE Sorry the script already executed write commands against the dataset. UNKILLABLE The busy script was sent by a master instance in the context of replication and cannot be killed. NOTBUSY No scripts in execution right now.
Jedis client	Could not get a resource from the pool java.net.SocketTimeoutException: connect timed out java.net.SocketTimeoutException: Read timed out No reachable node in cluster Caused by: java.lang.NumberFormatException: For input string: "6379@13028" No more cluster attempts left Unexpected end of stream java.lang.Long cannot be cast to java.util.List Broken pipe (Write failed) No way to dispatch this command to Redis Cluster because keys have different slots
Lettuce client	Connection to xxx not allowed. This Partition is not known in the cluster view. io.lettuce.core.RedisConnectionException: Unable to connect to xxx java.nio.channels.UnresolvedAddressException ERR Unknown sentinel subcommand 'master' Some instance versions do not support the RESP3 protocol, which causes an "unknown command" error.
Redisson client	org.redisson.client.RedisConnectionException: Unable to connect to Redis server xxx No enum constant org.redisson.cluster.ClusterNodeInfo.Flag.NOFAILOVER
Spring Data Redis client	NOPERM this user has no permissions to run the 'config\|get' command
StackExchange.Redis client	Multiple databases are not supported on this server; cannot switch to database
Predis client	Error while reading line from the server.
phpredis client	Cannot assign requested address redis protocol error, got ' ' as reply type byte php_network_getaddresses: getaddrinfo failed: Temporary failure in name resolution
Go-redis client	panic: got 4 elements in cluster info address, expected 2 or 3
node-redis client	SCAN command loops indefinitely or returns no data

General Redis exceptions

ERR illegal address

Possible cause: The IP address of your client is not added to a whitelist of the Tair instance.

Solution: Add the IP address of your client to a whitelist of the Tair instance. For more information, see Perform diagnostics on connections.

ERR Sentinel compatibility mode is disabled

Possible cause: The Sentinel-compatible mode is not enabled for the Tair instance.

Solution: Enable the Sentinel-compatible mode for the instance in the console. For more information, see Enable the Sentinel-compatible mode.

ERR max number of clients reached

Possible cause: The maximum number of connections to the Tair instance is reached.

Solution:

Check whether connection leaks occur on the client. For example, check whether the close function is invoked after JedisPool is used on the Jedis client.
Check whether the current connection session runs as expected. For more information, see Manage instance sessions. You can terminate the session or upgrade the instance configurations to increase the maximum number of connections to the instance.

NOAUTH

Possible cause: Password-based authentication is configured for the Tair instance, but the client does not provide a password or provides an incorrect password.

Solution: Use the correct username and password. Logon methods for instances.

Note

If you use Lettuce client versions 6.4.0.RELEASE through 6.4.1.RELEASE, this error may occur even if you provide the correct password. This issue was introduced when Lettuce added support for CLIENT SETINFO. It was fixed in version 6.4.2.RELEASE. redis/lettuce#3035.

If you encounter this issue, you can manually switch the protocol to RESP2 or upgrade the client to Lettuce 6.4.2.RELEASE or later. If you use a Spring Data Redis client, upgrade to Spring Data Redis 3.4.2 or later.

WRONGPASS invalid username-password pair

Possible cause: The password is invalid.

Solution: Use the correct account username and password to connect to the instance. For more information, see Connect to an instance.

Note

If the Sentinel-compatible mode is enabled for the instance, refer to the Use the Sentinel-compatible mode to connect to an instance topic.

ERR invalid password

Possible cause: The password is invalid.

Solution: Use the correct account username and password to connect to the instance. For more information, see Connect to an instance.

Note

If this error is reported in Data Management (DMS), the possible cause is that the password saved by DMS during the last logon does not match the current password for the instance. In the DMS instance list, find the instance and choose More > Edit in the Actions column. Then, enter the new password in the Database Password field and try again.

Connection reset by peer

Possible cause: The connection is closed due to an exception on the client buffer.

Solution: Check the application code or adjust the client buffer size. See the Unexpected end of stream section.

UnknownHostException

Alternatively, the failed to connect: xxx.redis.rds.aliyuncs.com could not be resolved error occurs.

Possible cause: The client cannot resolve the domain name of the Tair instance.

Solution: Configure the DNS server correctly. For more information, see How do I troubleshoot connection issues caused by failed DNS resolution?

OOM: Used memory > 'maxmemory'

Possible cause: The maximum memory configured for the Tair instance is reached.

Note

If the Tair instance uses the cluster architecture, the memory usage of a data shard may exceed the maximum memory configured for the data shard.

Solution:

If the memory usage of the instance reaches 100%, we recommend that you upgrade the instance configurations. For more information, see Change the configurations of an instance.
If the memory usage of a single data shard reaches 100%, large keys may exist in the instance. You can use the offline key analysis or instance diagnostics feature to identify the cause.

WRONGTYPE: Wrong data type

Possible cause: Command does not match the key's data type, such as running a HASH command on a String key.

Solution: Fix the incorrect code or command. Redis Commands.

ERR unknown command 'xxx'

Possible cause: The instance does not support this command.

The ERR unknown command 'WAIT' error indicates that the WAIT command is unsupported in proxy mode for cluster architecture. Use the direct link mode.

Solution: Verify command support for your instance version. Command support and limits for Tair (Enterprise Edition), Command support and limits for Redis Open-Source Edition, and Command limits for instances that use cluster architecture or read/write splitting.

Note

Upgrade to the latest minor version for new features and improved stability. Upgrade the minor version and proxy version.

Command 'xxx' not supported

Possible cause: Specific commands of Tair are disabled in Alibaba Cloud, or these commands are specified by #no_loose_disabled-commands. For more information, see Commands supported by Redis Open-Source Edition and Disable high-risk commands.

Solution: Delete the command that you want to run from the disabled commands specified by #no_loose_disabled-commands.

NOPERM this user has no permissions to run the 'xxx'

Possible cause: Specific commands of Tair are disabled in Alibaba Cloud, or these commands are specified by #no_loose_disabled-commands. For more information, see Commands supported by Redis Open-Source Edition and Disable high-risk commands.

Solution: Delete the command that you want to run from the disabled commands specified by #no_loose_disabled-commands.

ERR FLUSHDB is not allowed in migrating mode

Possible cause: When the number of data shards is changing for a Tair cloud-native cluster instance, the FLUSHDB and FLUSHALL commands are disabled.

Solution: Wait until the change ends for the Tair cloud-native cluster instance. For more information, see Adjust the number of shards for an instance.

CROSSSLOT: Keys not in the same slot

Possible cause: Commands that involve multiple keys across slots, such as DEL, MSET, and MGET, are not supported for Tair cluster instances in direct connection mode.

Solution:

Before you run a command that involves multiple keys, use the CLUSTER KEYSLOT command to ensure that all the keys reside in the same slot.
Change key names and implement hash tags to ensure that the involved keys are allocated in the same slot. However, it is important to prevent data skew when you use hash tags.
Change the instance to a cluster instance in proxy mode that supports commands involving multiple keys across slots, such as DEL, MGET, and MSET. For more information, see Features of proxy nodes.

Read-only instance error

Possible cause: During a master-replica switchover, configuration change, or minor version update for your Tair instance, transient connections occur and the instance remains read-only for up to 30 seconds.

Solution: Wait until the instance recovers. No manual operations are required. Design the reconnection and exception handling mechanisms for your application. For more information, see Change the configurations of an instance.

Failed to connect to any host resolved for DNS name

Possible cause: Incorrect whitelist configuration.

Solution: Add the client IP address to the whitelist. Configure an IP Whitelist.

Note

If you connect over the public network, add your egress IP address to the whitelist. Find your egress IP at https://cip.cc/.

Redis-cli exceptions

Connection reset by peer

Possible cause: The standard-architecture instance has TLS/SSL enabled, but you connected without a certificate.

Solution:

Connect with a certificate. Connect to an instance over a TLS/SSL-encrypted connection.
If you do not need to use TLS/SSL encryption, disable TLS encryption and try again.

ERR must use ssl connection in ssl port

Possible cause: The cluster-architecture instance has TLS/SSL enabled, but you connected without a certificate.

Solution:

Connect with a certificate. Connect to an instance over a TLS/SSL-encrypted connection.
If you do not need to use TLS/SSL encryption, disable TLS encryption and try again.

General proxy exceptions

ERR client IP is not in whitelist

Possible cause: The IP address of your client is not added to a whitelist of the Tair instance.

Solution: Add the IP address of your client to a whitelist of the Tair instance. For more information, see Perform diagnostics on connections.

NOWRITE: Cannot write to a read-only instance

Alternatively, the NOREAD You can't read against a non-read redis error occurs.

Possible cause: Your instance has overdue payments or has expired. The instance is in the Locked state.

Solution: Add funds to your account or renew the instance. For more information, see Expiration and overdue payments.

ERR syntax error

Possible cause: Incorrect command syntax, such as passing three parameters when four are required.

Solution: Check the command syntax. Redis Commands.

ERR no such db node

Possible cause: When you run an in-house command of Tair, the specified db node parameter is invalid.

Solution: Specify the db node parameter correctly. The value of db node must be less than the number of data shards in the instance. For more information, see In-house commands for instances in proxy mode.

ERR 'xxx' command keys must in same slot

Possible cause: A transaction or script accesses keys from different slots in a Tair cluster instance.

Solution: Modify the transaction or script. You can use the CLUSTER KEYSLOT command to query the slot in which a requested key is stored.

Important

Tair cluster instances use the Cyclic Redundancy Check (CRC) algorithm to evenly distribute keys across different slots. If you want to store keys in the same slot, you can use hash tags. However, this may cause data skew. Proceed with caution.

EVAL/EVALSHA: Key count must be positive

Possible cause: No keys are specified or the numkeys parameter is set to a value less than or equal to 0 for the EVAL and EVALSHA commands.

Solution: When you use the EVAL and EVALSHA commands, you must specify at least one key and set the numkeys parameter to a value greater than 0. For more information, see Usage of Lua scripts.

Too many pending requests

Possible cause: Pending requests are piled up in the backend of Tair because the client uses an invalid pipeline.

Solution: Reduce the number of pipelined requests.

ERR redis temporary failure

Possible cause: When you connect to a node of your Tair instance, a timeout error occurs due to network jitter, excessive connections, a master-replica switchover, or an ongoing slow query.

Solution: Wait until the instance recovers. No manual operations are required. Design the reconnection and exception handling mechanisms for your application.

ERR redis temporary failure (ErrorCode 7002)

Possible cause: When you connect to a node of your Tair instance, a timeout error occurs due to an ongoing instance configuration change or master-replica switchover.

Solution: Wait until the instance recovers. No manual operations are required. Design the reconnection and exception handling mechanisms for your application.

Lua scripts and transactions

NOSCRIPT: No matching script

Possible cause: When you run the EVALSHA command, the script corresponding to the SHA1 value is not cached to the Tair instance.

Solution: Run the EVAL or SCRIPT LOAD command to cache the required script to the Tair instance and try again. For more information, see Handle the NOSCRIPT error.

BUSY Redis is busy running a script. You can only call SCRIPT KILL or SHUTDOWN NOSAVE.

Possible cause: A Lua script timed out.

Solution: Run the SCRIPT KILL command to terminate the execution of the script or wait until the execution ends. For more information, see Handle timeouts of Lua scripts.

EVAL command not supported

Possible cause: EVAL-related commands cannot be run.

Solution: Update your instance to the latest minor version. For more information, see Update the minor version of an instance.

Keys for eval/evalsha must be in same slot

Possible cause: The keys involved in the Lua script do not reside in the same slot. This error is common in cluster instances.

Solution: Modify the Lua script. You can query the slot in which a key resides by running the CLUSTER KEYSLOT command. For more information, see Limits on Lua scripts in cluster instances.

ERR bad Lua script for Redis cluster

Possible cause: This error may be caused by limits of proxy nodes on Lua scripts.

Solution: Specify all keys in arrays. Example: EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo {foo}bar. Keys cannot be replaced by Lua variables. For more information, see Limits on Lua scripts in cluster instances.

EXECABORT: Transaction discarded

Possible cause: The command that you run in a transaction has syntax mistakes or errors.

Solution: Check your code logic and correct the syntax mistakes of the command.

Unkillable script with write commands

Possible cause: Write operations that are involved in the current Lua script have been performed. In this case, the SCRIPT KILL command cannot be run.

Solution: Find the instance in the console and click restart in the Actions column. For more information, see Restart an instance.

UNKILLABLE: Cannot kill replicated scripts

Possible cause: The current Lua script is forwarded by the master node to the corresponding replica node. In this case, the SCRIPT KILL command cannot be run.

Solution: Find the instance in the console and click restart in the Actions column. For more information, see Restart an instance.

NOTBUSY

Possible cause: No Lua scripts are being executed.

Solution: No manual operations are required. Do not run the SCRIPT KILL command.

Jedis client

Resource pool acquisition failure

Possible cause: Jedis connections cannot be borrowed from JedisPool.

When the blockWhenExhausted parameter is set to true, which is the default value, the client waits several milliseconds specified by the maxWaitMillis parameter if no connections are available from JedisPool. If the client still cannot obtain an available Jedis connection after waiting for a long time, the following exception is thrown:
```
redis.clients.jedis.exceptions.JedisConnectionException: Could not get a resource from the pool
    ...
Caused by: java.util.NoSuchElementException: Timeout waiting for idle object
    at org.apache.commons.pool2.impl.GenericObjectPool.borrowObject(GenericObjectPool.java:449)
```

When the blockWhenExhausted parameter is set to false, the following exception is thrown if no connections are available from JedisPool:

redis.clients.jedis.exceptions.JedisConnectionException: Could not get a resource from the pool
    ...
Caused by: java.util.NoSuchElementException: Timeout waiting for idle object
    at org.apache.commons.pool2.impl.GenericObjectPool.borrowObject(GenericObjectPool.java:449)

Solution: Consider the following aspects to troubleshoot the error:

Connection leaks

By default, maxTotal is set to 8. The following code shows that the Jedis client borrows connections from JedisPool for eight times but does not return these connections. This is why the Jedis client cannot run the jedisPool.getResource().ping() command at the ninth attempt to obtain another connection from JedisPool.

GenericObjectPoolConfig poolConfig = new GenericObjectPoolConfig();
JedisPool jedisPool = new JedisPool(poolConfig, "127.0.0.1", 6379);
// The client borrows connections from JedisPool for eight times, but does not return these connections. 
for (int i = 0; i < 8; i++) {
    Jedis jedis = null;
    try {
        jedis = jedisPool.getResource();
        jedis.ping();
    } catch (Exception e) {
        logger.error(e.getMessage(), e);
    }
}
jedisPool.getResource().ping();

Recommended code:

Jedis jedis = null;
try {
    jedis = jedisPool.getResource();
    // The command that you want to run. 
    jedis.executeCommand()
} catch (Exception e) {
    // If the command involves a key, we recommend that you make configurations to display the key in error logs. This way, you can use the key to identify the data shard on which issues occur. 
    logger.error(e.getMessage(), e);
} finally {
    // The client does not close a borrowed connection. Instead, the client returns the connection to JedisPool. 
    if (jedis != null) 
        jedis.close();
}

A small value for the maxTotal parameter
When the system has a large number of operations being processed in concurrency, a small value for the maxTotal parameter may cause exceptions. For example, it takes about 1 ms to run a command on average. This is calculated by using the following formula: Amount of time consumed to borrow or return resources + Amount of time consumed for Jedis to run the command + Network latency. The number of queries per second (QPS) of a connection is about 1,000, and the expected total QPS is 50,000. In theory, you need a maxTotal value of 50 to achieve the expected QPS of 50,000. The maxTotal value is obtained by dividing 50,000 by 1,000.
In this case, you can run the following command on your client to obtain the number of client connections. You can adjust the value of maxTotal based on the obtained value.
```
netstat -an | grep 6379 | grep EST | wc -l
```
Connection blocking
When connections to the Tair instance are blocked due to reasons such as slow queries, all connections wait within the specified timeout period. In this case, when a large number of operations are processed in concurrency, a timeout error may be reported. For more information, see java.net.SocketTimeoutException: connect timed out.

Connection rejected

When you attempt to obtain a connection from JedisPool and no connections are available, Jedis attempts to create a Jedis connection. However, the connection attempt is rejected and an exception is thrown. Example:

redis.clients.jedis.exceptions.JedisConnectionException: Could not get a resource from the pool
    at redis.clients.util.Pool.getResource(Pool.java:50)
    at redis.clients.jedis.JedisPool.getResource(JedisPool.java:99)
    at TestAdmin.main(TestAdmin.java:14)
Caused by: redis.clients.jedis.exceptions.JedisConnectionException: java.net.ConnectException: Connection refused
    at redis.clients.jedis.Connection.connect(Connection.java:164)
    at redis.clients.jedis.BinaryClient.connect(BinaryClient.java:80)
    at redis.clients.jedis.BinaryJedis.connect(BinaryJedis.java:1676)
    at redis.clients.jedis.JedisFactory.makeObject(JedisFactory.java:87)
    at org.apache.commons.pool2.impl.GenericObjectPool.create(GenericObjectPool.java:861)
    at org.apache.commons.pool2.impl.GenericObjectPool.borrowObject(GenericObjectPool.java:435)
    at org.apache.commons.pool2.impl.GenericObjectPool.borrowObject(GenericObjectPool.java:363)
    at redis.clients.util.Pool.getResource(Pool.java:48)
    ... 2 more
Caused by: java.net.ConnectException: Connection refused
    at java.net.PlainSocketImpl.socketConnect(Native Method)
    at java.net.AbstractPlainSocketImpl.doConnect(AbstractPlainSocketImpl.java:339)
    at java.net.AbstractPlainSocketImpl.connectToAddress(AbstractPlainSocketImpl.java:200)
    at java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:182)
    at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:392)
    at java.net.Socket.connect(Socket.java:579)
    at redis.clients.jedis.Connection.connect(Connection.java:158)
    ... 9 more

at redis.clients.jedis.Connection.connect(Connection.java:158) indicates that Jedis attempts to create a socket connection and invoke the connect function, but the connection attempt is rejected. Jedis source code:

socket.setSoLinger(true, 0); 
158:  socket.connect(new InetSocketAddress(host, port), connectionTimeout);

Typically, to address this issue, you must check whether the domain name configuration of the Tair instance is correct and check the network connection within the corresponding time period.

java.net.SocketTimeoutException: connect timed out

Possible cause: The connection between your client and the Tair instance timed out.

Solution: Refer to the How do I troubleshoot connection issues in Tair? topic.

java.net.SocketTimeoutException: Read timed out

Possible cause: A Jedis API call timed out due to unstable network connection, short read/write timeout periods, slow queries, or connection blocking.

Solution: Increase the timeout period or perform instance diagnostics to check whether a performance issue or an exception occurs at the corresponding point in time.

Note

If this error occurs in DMS, the VPC endpoint or port may have changed. In the DMS console, right-click the instance in the database instance list and select Edit Instance. Set Entry Method to Connection String Address, enter the updated endpoint in Connection String Address, and try again.

No reachable node in cluster

Possible cause: JedisCluster is inaccessible.

Solution: The first time your client connects to the Tair instance, check whether the IP address of the client is added to a whitelist of the Tair instance. If this is not your first time connecting to the Tair instance, perform instance diagnostics to identify the cause.

Caused by: java.lang.NumberFormatException: For input string: "6379@13028"

Possible cause: ClusterNodeInformationParser is introduced in Jedis 2.8.0 and earlier to resolve the output of cluster slots. However, open source Redis has changed the type of the output. This is why the NumberFormatException error is reported.

Solution: Update your Jedis client to 2.9.0 or later.

No more cluster attempts left

Possible cause: An API call timed out and the five retries also failed. By default, after an API call times out, JedisCluster retries five times.

Solution: Increase the timeout period or perform instance diagnostics.

Unexpected end of stream

Possible cause: An exception occurs on the Jedis client buffer. You can consider the following aspects to troubleshoot the error:

Multiple threads sharing one connection

Typically, one thread uses one Jedis connection. The following code shows that two threads share one Jedis connection:

new Thread(new Runnable() {
    public void run() {
        for (int i = 0; i < 100; i++) {
            jedis.get("hello");
        }
    }
}).start();
new Thread(new Runnable() {
    public void run() {
        for (int i = 0; i < 100; i++) {
            jedis.hget("haskey", "f");
        }
    }
}).start();

To prevent this issue and ensure thread security, you can use JedisPool to manage Jedis connections.

Long-time idle connections
The server closes long-time idle connections. Query the timeout settings of the instance and related settings of JedisPool to determine whether to periodically check and clean up long-time idle connections.
Note
By default, Tair does not close a long-time idle connection. If you modify the value of the timeout parameter, this error may be reported. For more information, see Specify a timeout period for idle client connections.

Solution: Check whether multiple threads share Jedis code or whether the server closes a long-time idle connection.

java.lang.Long cannot be cast to java.util.List

Possible cause: This error is reported if the same Jedis connection is shared among multiple threads. This is because Jedis itself is not thread-safe and must not be used concurrently across multiple threads.

Solution: Use one Jedis connection in a single thread. For that matter, you can use JedisPool.

Broken pipe (Write failed)

Possible cause: After a timeout error occurs on the Jedis client in single connection mode and the client closes the socket, you continue to write data to the instance.

Solution: Use one Jedis connection in a single thread. For that matter, you can use JedisPool.

Keys are in different slots

Possible cause: JedisCluster performs operations on keys that reside in different slots.

Solution: Modify keys by means of hash tags.

Note

You can also use the proxy mode to disable limits of the cluster architecture.

Lettuce client

Connection to xxx not allowed. This partition is not known in the cluster view.

Possible cause: By default, validateClusterNodeMembership is set to true and refreshOption is set to null for the Lettuce client. After the routing address of the Tair instance changes, the route table is not updated because refreshOption is set to null. In this case, the error is reported for validateClusterNodeMembership.

Solution: Specify the refreshOption parameter and set the validateClusterNodeMembership parameter to false. For more information, see Lettuce.

io.lettuce.core.RedisConnectionException: Unable to connect xxx

Possible cause: The connection between your client and the Tair instance timed out.

Solution: Refer to the How do I troubleshoot connection issues in Tair? topic.

java.nio.channels.UnresolvedAddressException

Possible cause: The error occurs most likely due to the Netty version.

Solution: Upgrade your Netty dependency. spring-projects/spring-boot#14307.

ERR Unknown sentinel subcommand 'master'

Possible cause: In master-replica Sentinel mode, the Lettuce client sends the Sentinel master/slave command to the Tair instance. However, an instance in Sentinel-compatible mode supports only the Sentinel get-master-addr-by-name command.

Solution: Modify your code to switch to a non-Sentinel mode. Tair uses an in-house high availability component. You do not need to use the Sentinel-compatible mode.

'Unknown command' error for unsupported RESP3 protocol

Possible cause: Redis 6.0 and later support the RESP3 protocol. You can run the HELLO command to switch the connection to the desired RESP protocol version. However, some instances of earlier versions do not support the HELLO command, leading to compatibility issues.

Solution: You can configure your program to use the RESP2 protocol to access the Tair instance. Example:

client.setOptions(ClientOptions.builder()
    .protocolVersion(ProtocolVersion.RESP2)
    .build());

Example when Spring Data Redis with Lettuce is used as the Redis client:

LettuceClientConfiguration lettuceClientConfiguration = LettuceClientConfiguration.builder().
    clientOptions(ClientOptions.builder().protocolVersion(ProtocolVersion.RESP2).build()).build();

return new LettuceConnectionFactory(redisClusterConfiguration, lettuceClientConfiguration);

Redisson client

org.redisson.client.RedisConnectionException: Unable to connect to Redis server xxx

Possible cause: The connection between your client and the Tair instance timed out.

Solution: Refer to the How do I troubleshoot connection issues in Tair? topic.

No enum constant org.redisson.cluster.ClusterNodeInfo.Flag.NOFAILOVER

Possible cause: Known bug in earlier Redisson versions. redisson/redisson#2399.

Solution: Update your Redisson client to 3.11.6 or later.

Spring Data Redis client

NOPERM this user has no permissions to run the 'config|get' command

Possible cause: The version of your instance is displayed as Redis 7.0 on the Instance Information page. The CONFIG command is disabled in Tair (Redis OSS-compatible) instances that run Redis 7.0.

At startup, Spring Data Redis runs the CONFIG SET command to set the notify-keyspace-events parameter and enable KeyspaceEventMessageListener. Because CONFIG GET/SET commands are disabled, this fails with a startup error.

Solution: Set keyspaceNotificationsConfigParameter to an empty string. Sample code: SpringRedisTest.zip. Spring Data Redis.

@EnableRedisRepositories(enableKeyspaceEvents = RedisKeyValueAdapter.EnableKeyspaceEvents.ON_STARTUP, keyspaceNotificationsConfigParameter = "")

If you use KeyExpirationListener, also set keyspaceNotificationsConfigParameter to an empty string in the constructor.

public RedisKeyExpirationListener(RedisMessageListenerContainer redisMessageListenerContainer) {
    super(redisMessageListenerContainer);
    setKeyspaceNotificationsConfigParameter(""); // Important
}

StackExchange.Redis client

Multiple databases not supported

Possible cause: The SELECT command is not supported for cluster instances.

Solution: Set the cluster_compat_enable parameter to 0 to disable the compatibility with open source Redis Cluster syntax. Then, restart your client and try again. For more information, see Configure instance parameters.

Predis client

Error while reading line from the server

Possible cause: The read request timed out. A slow query may be in progress.

Solution: Increase the timeout period or set read_write_timeout to 0 or -1. For more information, see Predis questions.

Phpredis client

Cannot assign requested address

Possible cause: The client connects to the Tair instance over a short-lived connection.

Solution: Change the connection method from connect to pconnect, or modify the tcp_max_tw_buckets kernel parameter on the client ECS instance. "Cannot assign requested address" error.

redis protocol error, got ' ' as reply type byte

Possible cause: Bug in an outdated phpredis version. phpredis/phpredis#1585.

Solution: Upgrade phpredis to the latest version.

php_network_getaddresses: getaddrinfo failed: Temporary failure in name resolution

Solution: Configure the DNS server correctly. For more information, see How do I troubleshoot connection issues caused by failed DNS resolution?

Possible cause: The client cannot resolve the domain name of the Tair instance.

Go-redis client

panic: got 4 elements in cluster info address, expected 2 or 3

Possible cause: Incompatible Go-redis client version with Redis 7.0 or later. redis/go-redis#2085.

Solution: Use go-redis 9.0 or later.

Node-redis client

SCAN command loops infinitely or returns no data

Possible cause: The SCAN command can return a cursor value exceeding JavaScript's maximum safe integer, Number.MAX_SAFE_INTEGER. This leads to an inaccurate cursor and infinite loop. redis/node-redis#2561.

Solution: Update your node-redis client to 5.0.0 or later.