No matching script. Please use EVAL.
This error occurs when trying to execute a Lua script by its SHA1 hash using EVALSHA, but the script is not present in the server's script cache. Redis caches scripts to avoid re-transmitting them, but this cache can be flushed.
- 1The Redis server was restarted, clearing the script cache.
- 2The `SCRIPT FLUSH` command was executed, manually clearing the cache.
- 3Connecting to a different Redis instance (e.g., a replica or a different server in a cluster) that never received the script.
A client attempts to run a script via EVALSHA, but the server has been restarted since the script was loaded.
# Assume this hash doesn't exist in the cache EVALSHA "e0e1f9fabcde252273c689364b4a034d3a7042a3" 0
expected output
(error) NOSCRIPT No matching script. Please use EVAL.
Fix 1
Implement a fallback from EVALSHA to EVAL
WHEN This is the standard, most robust handling pattern
try {
redis.evalsha("e0e1...", 0);
} catch (e) {
if (e.message.includes("NOSCRIPT")) {
redis.eval("return 'hello'", 0);
}
}Why this works
Upon receiving a NOSCRIPT error, the client should resend the request using EVAL with the full script body. The script will be executed and cached automatically, so subsequent EVALSHA calls will succeed.
Fix 2
Use SCRIPT LOAD to pre-load scripts
WHEN During application startup or after a server restart
SCRIPT LOAD "return redis.call('SET', KEYS[1], ARGV[1])"
# returns: "a1b2c3d4..." (the hash)
# now EVALSHA will work
EVALSHA "a1b2c3d4..." 1 mykey "myvalue"Why this works
SCRIPT LOAD adds the script to the cache without executing it, returning the SHA1 hash. This ensures the script is available for EVALSHA calls later.
✕ Only use EVAL and never use EVALSHA
Using only EVAL increases network traffic by sending the full script every time. The EVALSHA/EVAL fallback is the optimal pattern.
Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev