Redis lets you run a Lua script either by sending its full source with EVAL or by sending a SHA1 digest with EVALSHA. Why does EVALSHA exist, what error must a client be ready for, and how do SCRIPT LOAD and SCRIPT EXISTS fit in?

## The bandwidth problem EVALSHA solves `EVAL` carries the entire Lua source in every request. A 2 KB script called 50,000 times a second is 100 MB/s of duplicated text, plus the parsing cost. Redis therefore keeps a **script cache**: whenever it executes a script it stores the body under the SHA1 hex digest of the exact bytes. `EVALSHA <sha1> numkeys key… arg…` then executes the cached copy, and the request shrinks to the digest. Because the key is a content digest, two clients that send byte-identical scripts share the cache entry, and you can compute the digest locally (any SHA1 implementation over the script text) instead of asking the server for it. A single trailing whitespace change makes a different script — this is a real source of "why is my cache full of near-duplicates". ## The cache is ephemeral — this is the whole lesson The script cache lives only in the server's memory and is deliberately not treated as data: - it is **not** written to RDB snapshots; - it is **not** stored in the AOF as a cache (only the script's *effects* are propagated); - `SCRIPT FLUSH [ASYNC|SYNC]` empties it; - a restart starts with an empty cache; - a replica promoted by failover generally has an empty (or differently populated) cache. Hence `EVALSHA` may fail with: ``` (error) NOSCRIPT No matching script. Please use EVAL. ``` This is not an exceptional condition to log and give up on — it is a normal part of the protocol. ## The required client pattern ``` try EVALSHA(sha, keys, args) catch NOSCRIPT: EVAL(body, keys, args) # or SCRIPT LOAD then retry EVALSHA ``` Two important consequences: 1. **The client must still hold the source.** EVALSHA never lets you stop shipping the script text with your application; it only lets you stop sending it on the wire most of the time. 2. **The fallback path is rarely exercised**, so it is rarely tested — and it fires precisely during incidents (after a restart, after a failover, after an operator ran `SCRIPT FLUSH`). Test it deliberately. Most mature client libraries (redis-py, Lettuce, ioredis, go-redis) encapsulate this in a "script object" that computes the digest, tries EVALSHA, and transparently reloads on NOSCRIPT. ## SCRIPT LOAD and SCRIPT EXISTS `SCRIPT LOAD <body>` compiles and caches the script **without executing it**, returning its SHA1. Use it to warm the cache at connection or deployment time. Note that in a Cluster the cache is per node, so warming means loading against every node you may talk to — and even then a restart re-empties it, so warming complements the NOSCRIPT handler, it does not replace it. `SCRIPT EXISTS <sha1> [<sha1> …]` returns an array of 1/0 telling you which digests are cached. It is handy in health checks and in deploy scripts, and for diagnosing a node that keeps returning NOSCRIPT. `SCRIPT FLUSH` empties the cache; it is the command that makes NOSCRIPT happen on a live system, so treat it as disruptive on a busy server. ## Semantics are identical `EVAL` and `EVALSHA` differ only in how the body reaches the server. Both execute atomically, both block the server for the duration, both require keys to be declared, and both propagate to replicas and the AOF the same way (effects replication). There is no execution-speed advantage to `EVALSHA` beyond skipping transmission and a re-parse. Since Redis 7.0 there are also `EVAL_RO` and `EVALSHA_RO`, which refuse write commands and can therefore run on replicas — the script equivalent of the read-only invocation. ## Diagnosing NOSCRIPT storms If a service suddenly floods with NOSCRIPT, the cause is almost always one of: a node restarted or failed over; someone ran `SCRIPT FLUSH`; a client is connecting to a node it never warmed (new node after a reshard, or connection pool spreading across a cluster); or the script text is being generated dynamically so each call has a different digest and the cache grows without ever hitting. That last case also leaks memory in the script cache, since entries are never evicted — which is one motivation for moving stable logic to Redis Functions, whose libraries are named and persisted.