The BUSY error occurs when a Lua script is running longer than Redis expects, blocking other clients from executing commands. Clients attempting to send commands receive a BUSY response, indicating they must wait or kill the script.
Redis enforces a maximum execution time for Lua scripts using the 'lua-time-limit' configuration (default 5 seconds). When a script exceeds this limit, Redis stops executing it but does not immediately terminate it. Instead, Redis enters a BUSY state where it accepts new client connections but responds to all regular commands with the BUSY error. In this state, only SCRIPT KILL, FUNCTION KILL, or SHUTDOWN NOSAVE commands are allowed. This is a safety mechanism to prevent long-running scripts from blocking all database operations indefinitely, though it does require intervention to resolve.
Connect to Redis and check the current status:
SCRIPT HELP
LOGGETOr use a Redis client library to monitor script execution. The SLOWLOG GET command can show recent slow operations.
Use the SCRIPT KILL command to stop the Lua script that is blocking other clients:
SCRIPT KILLThis only works if the script hasn't performed any write operations. If it has, you may need to use SHUTDOWN NOSAVE instead.
If SCRIPT KILL returns an error (because the script performed writes), you must force shutdown:
SHUTDOWN NOSAVEThis terminates Redis immediately without saving the database. Use only when necessary, as unsaved data will be lost.
Once Redis recovers, investigate which Lua script caused the BUSY state:
1. Check application logs for script execution patterns
2. Use SLOWLOG GET to identify slow commands:
SLOWLOG GET 103. Review EVALSHA or EVAL calls that exceed reasonable execution time
4. Profile the script locally before deploying
Review and optimize the problematic script:
1. Avoid SCAN-like operations over large key sets
2. Use pipelining instead of sequential commands
3. Minimize conditional logic inside scripts
4. Use local variables instead of repeated Redis calls
5. Break long operations into smaller chunks
Example of optimized script:
-- Bad: inefficient loop
for i=1,1000000 do
redis.call('INCR', 'counter:' .. i)
end
-- Better: use pipelining or batch operations
local keys = {}
for i=1,1000000 do
table.insert(keys, 'counter:' .. i)
end
return redis.call('MGET', keys)If you have legitimate long-running scripts, increase the lua-time-limit configuration:
CONFIG SET lua-time-limit 10000This increases the limit to 10 seconds (in milliseconds). Make the change permanent in redis.conf:
lua-time-limit 10000WARNING: Long-running scripts still block all other clients, so this should only be used as a temporary measure while optimizing scripts.
In your application code, implement timeouts and error handling:
// Node.js example with redis library
const client = redis.createClient();
try {
const result = await client.evalsha(scriptSHA, 0, timeout);
} catch (error) {
if (error.message.includes('BUSY')) {
// Handle BUSY error: retry after delay, kill script, etc.
await sleep(1000);
// Attempt retry or fallback
}
}Add monitoring to track script execution times and alert on anomalies.
The BUSY error is a symptom of poor script performance, not a root cause. Redis does not kill the script when lua-time-limit is exceededโit merely stops accepting new script executions and marks the server as BUSY. The only way to recover without restarting is SCRIPT KILL (if no writes occurred) or SHUTDOWN NOSAVE. For high-traffic systems, consider: 1) using the SCRIPT DEBUG command to test scripts in debug mode before deployment, 2) implementing a separate Redis instance for long-running scripts, 3) using Redis modules that support non-blocking operations, or 4) breaking scripts into smaller atomic operations executed via transactions instead of Lua. In Redis Cluster, BUSY errors in one node can propagate to the entire cluster, making it critical to ensure scripts are fast. Always profile and test scripts with realistic data sizes before production deployment.
ERR fsync error
How to fix "ERR fsync error" in Redis
CLUSTERDOWN The cluster is down
How to fix 'CLUSTERDOWN The cluster is down' in Redis
ERR Job for redis-server.service failed because a timeout was exceeded
Job for redis-server.service failed because a timeout was exceeded
ERR Unbalanced XREAD list of streams
How to fix "ERR Unbalanced XREAD list" in Redis
ERR syntax error
How to fix "ERR syntax error" in Redis