Tair (Redis® OSS-Compatible):Lua script specifications and common errors

Optimize memory and network overhead

Caching a large number of functionally repetitive scripts consumes significant memory and can even trigger an out of memory (OOM) error. The following is an example of incorrect usage:

EVAL "return redis.call('set', 'k1', 'v1')" 0
EVAL "return redis.call('set', 'k2', 'v2')" 0

Clear Lua script memory

-OOM command not allowed when used memory > 'maxmemory'.

Solution:

In addition, avoid writing excessively large Lua scripts to prevent high memory consumption. Do not perform bulk data writes within a Lua script, as this can cause a sharp increase in memory usage and may lead to an OOM error. If your business logic allows, we recommend enabling data eviction (enabled by default with the volatile-lru policy) to save memory space. However, the instance does not evict the Lua script cache, regardless of whether data eviction is enabled.

NOSCRIPT error

(error) NOSCRIPT No matching script. Please use EVAL.

Solution:

Use the EVAL or SCRIPT LOAD command to cache the script on the instance, and then retry. However, the instance does not guarantee the persistence or replication of Lua scripts. In some scenarios, such as an instance migration or a configuration change, the Lua script cache may be cleared. Therefore, your client application must be able to handle this error. For more information, see Persistence and replication issues.

import redis
import hashlib

# This function takes a Lua script as a string and returns its SHA1 digest.
def calcSha1(strin):
    sha1_obj = hashlib.sha1()
    sha1_obj.update(strin.encode('utf-8'))
    sha1_val = sha1_obj.hexdigest()
    return sha1_val

class MyRedis(redis.Redis):

    def __init__(self, host="localhost", port=6379, password=None, decode_responses=False):
        redis.Redis.__init__(self, host=host, port=port, password=password, decode_responses=decode_responses)

    def prepend_inLua(self, key, value):
        script_content = """\
        local suffix = redis.call("get", KEYS[1])
        local prefix = ARGV[1]
        local new_value = prefix..suffix
        return redis.call("set", KEYS[1], new_value)
        """
        script_sha1 = calcSha1(script_content)
        if self.script_exists(script_sha1)[0]:      # Check if the script is cached in Redis.
            return self.evalsha(script_sha1, 1, key, value) # If cached, run the script with EVALSHA.
        else:
            return self.eval(script_content, 1, key, value) # Otherwise, run the script with EVAL, which also caches it. Alternatively, you could use SCRIPT LOAD and then EVALSHA.

r = MyRedis(host="r-******.redis.rds.aliyuncs.com", password="***:***", port=6379, decode_responses=True)

print(r.prepend_inLua("k", "v"))
print(r.get("k"))
            

Lua script timeout errors

• Because Lua scripts execute atomically, a slow-running script can block the instance. If a script runs for more than 5 seconds, the instance returns a BUSY error for all other commands until the script finishes executing.

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

  Solution:

  You can use the SCRIPT KILL command to terminate the Lua script or wait for it to complete.

  Note

  • The SCRIPT KILL command does not take effect during the first 5 seconds of a slow script's execution because the instance is blocked.

  • When writing Lua scripts, estimate their execution time and check for issues like infinite loops. This helps prevent long-running scripts from blocking the instance and making the service unavailable. If necessary, break down long scripts into smaller ones.

• If the current Lua script has already executed a write command, the SCRIPT KILL command will not work. An example error is shown below:

  (error) UNKILLABLE Sorry the script already executed write commands against the dataset. You can either wait the script termination or kill the server in a hard way using the SHUTDOWN NOSAVE command.

  Solution:

  In the console, go to the Instances page and click restart for the corresponding instance.

Persistence and replication issues

The instance caches executed Lua scripts indefinitely unless it is restarted or the SCRIPT FLUSH command is called. However, in certain situations, such as an instance migration, a configuration change, a version upgrade, or an HA switchover, the instance does not guarantee the persistence of Lua scripts or their replication to other nodes.

Solution:

Because the instance does not guarantee script persistence or replication, you should store all Lua scripts locally. When necessary, use the EVAL or SCRIPT LOAD command to recache the scripts on the instance. This prevents NOSCRIPT errors that can occur if the script cache is cleared during operations like an instance restart or an HA switchover.

Cluster architecture constraints

• To ensure atomicity, a Lua script cannot be split and must be executed on a single shard in a cluster architecture. The instance typically uses a key to determine which shard to route the command to. Therefore, you must specify at least one key when you execute a Lua script in a cluster. If a script accesses multiple keys, they must all belong to the same slot; otherwise, the script will fail or return incorrect results. Commands without keys, such as KEYS, SCAN, and FLUSHDB, can run but will only return data from a single shard. These limitations are inherent to the Redis Cluster architecture.

• Running the SCRIPT LOAD command on a single node does not guarantee that the script is stored on other nodes.

Error codes in proxy mode

The proxy performs syntax checks to proactively identify cases where keys span multiple slots. This helps detect issues early for easier troubleshooting. The proxy's checking method differs from that of the Lua virtual machine, resulting in additional restrictions when executing Lua commands in proxy mode. For example, the UNPACK command is not supported, and EVAL, EVALSHA, and SCRIPT-series commands cannot be used within MULTI/EXEC transactions.

You can also disable some of the proxy's Lua syntax checks by turning off the script_check_enable parameter.

Additionally, for a read/write splitting instance, if the readonly_lua_route_ronode_enable parameter is enabled, the proxy checks if a Lua script contains only read-only commands to determine whether it can be forwarded to a read-only node. This check logic imposes limitations on Lua syntax.

The following are the specific error codes and their causes.

Redis Cluster architecture limitations

• Error code: -ERR for redis cluster, eval/evalsha number of keys can't be negative or zero\r\n

  Description: You must specify at least one key when executing a Lua script. The proxy uses the key to determine which shard to forward the script to.

  # Correct example
  EVAL "return redis.call('get', KEYS[1])" 1 fooeval
  
  # Incorrect example
  EVAL "return redis.call('get', 'foo')" 0

• Error code: -ERR 'xxx' command keys must in same slot

  Description: All keys in a Lua script must belong to the same slot.

  # Correct example:
  EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo {foo}bar
  
  # Incorrect example:
  EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo foobar

Proxy Lua syntax restrictions

• Error code: -ERR bad lua script for redis cluster, nested redis.call/redis.pcall

  Description: Nested Redis calls are not supported. Use local variables as an alternative.

  # Correct example
  EVAL "local value = redis.call('GET', KEYS[1]); redis.call('SET', KEYS[2], value)" 2 foo bar
  
  # Incorrect example
  EVAL "redis.call('SET', KEYS[1], redis.call('GET', KEYS[2]))" 2 foo bar

• Error code: -ERR bad lua script for redis cluster, first parameter of redis.call/redis.pcall must be a single literal string

  Description: The command invoked within redis.call/pcall must be a string literal.

  # Correct example
  eval "redis.call('GET', KEYS[1])" 1 foo
  
  # Incorrect example
  eval "local cmd = 'GET'; redis.call(cmd, KEYS[1])" 1 foo

Read/write permission issues

• Error code: -ERR Write commands are not allowed from read-only scripts

  Description: Lua scripts sent with the EVAL_RO command cannot contain write commands.

• Error code: -ERR bad write command in no write privilege

  Description: Lua scripts sent from a read-only account cannot contain write commands.

Unsupported commands

• Error code: -ERR script debug not support

  Description: The proxy does not currently support the SCRIPT DEBUG command.

• Error code: -ERR bad lua script for redis cluster, redis.call/pcall unkown redis command xxx

  Description: The Lua script contains a command that is not supported by the proxy. For more information, see Command restrictions on cluster and read/write splitting instances.

Lua syntax errors

• Error code: -ERR bad lua script for redis cluster, redis.call/pcall expect '(' or -ERR bad lua script for redis cluster, redis.call/redis.pcall definition is not complete, expect ')'

  Note: This is a Lua syntax error because the redis.call function must be followed by a complete pair of parentheses: ( and ).

• Error code: -ERR bad lua script for redis cluster, at least 1 input key is needed for ZUNIONSTORE/ZINTERSTORE

  Description: The numkeys parameter of the ZUNIONSTORE and ZINTERSTORE commands must be greater than 0.

• Error code: -ERR bad lua script for redis cluster, ZUNIONSTORE/ZINTERSTORE key count < numkeys

  Description: The actual number of keys for the ZUNIONSTORE or ZINTERSTORE command is less than the specified numkeys value.

• Error code: -ERR bad lua script for redis cluster, xread/xreadgroup command syntax error

  Description: The syntax of the XREAD or XREADGROUP command is incorrect. Check the number of parameters.

• Error code: -ERR bad lua script for redis cluster, xread/xreadgroup command syntax error, streams must be specified

  Description: The XREAD and XREADGROUP commands must include the streams parameter.

• Error code: -ERR bad lua script for redis cluster, sort command syntax error

  Description: The syntax of the SORT command is incorrect.