How to fix BUSY Redis is busy running a script in Redis

RedisINTERMEDIATEHIGHUpdated Dec 29, 2025· 155 views

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.

Quick fix

Fixes BUSY

SCRIPT HELP
LOGGET
  1. Check if a script is currently running
  2. Kill the currently running script
  3. If SCRIPT KILL fails, use SHUTDOWN NOSAVE
  4. Identify which script is causing the issue
redis — error
SCRIPT HELP
LOGGET
BUSY Redis is busy running a script

What this error means

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.

Typical symptoms

  • Client commands fail with 'BUSY Redis is busy running a script' error
  • Database appears unresponsive to normal read/write operations
  • Only SCRIPT KILL commands are accepted by Redis
  • Application timeouts increase dramatically during error occurrence
  • Multiple clients report BUSY errors simultaneously
  • CI/CD pipelines fail when accessing Redis during script execution

Common causes

  1. Lua script execution exceeds the lua-time-limit (default 5 seconds)
  2. Script contains expensive operations like scanning large key sets (SCAN with many keys)
  3. Script performs blocking operations or inefficient algorithms
  4. High database load causing script operations to take longer
  5. Insufficient lua-time-limit configuration for legitimate long-running operations
  6. Multiple concurrent scripts being executed, causing cumulative delays

How to fix "BUSY Redis is busy running a script"

1Check if a script is currently running

Connect to Redis and check the current status:

redis
SCRIPT HELP
LOGGET

Or use a Redis client library to monitor script execution. The SLOWLOG GET command can show recent slow operations.

2Kill the currently running script

Use the SCRIPT KILL command to stop the Lua script that is blocking other clients:

redis
SCRIPT KILL

This only works if the script hasn't performed any write operations. If it has, you may need to use SHUTDOWN NOSAVE instead.

3If SCRIPT KILL fails, use SHUTDOWN NOSAVE

If SCRIPT KILL returns an error (because the script performed writes), you must force shutdown:

redis
SHUTDOWN NOSAVE

This terminates Redis immediately without saving the database. Use only when necessary, as unsaved data will be lost.

4Identify which script is causing the issue

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:

redis
SLOWLOG GET 10

3. Review EVALSHA or EVAL calls that exceed reasonable execution time
4. Profile the script locally before deploying

5Optimize the Lua script

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:

lua
-- 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)
6Increase lua-time-limit if necessary

If you have legitimate long-running scripts, increase the lua-time-limit configuration:

redis
CONFIG SET lua-time-limit 10000

This increases the limit to 10 seconds (in milliseconds). Make the change permanent in redis.conf:

bash
lua-time-limit 10000

WARNING: Long-running scripts still block all other clients, so this should only be used as a temporary measure while optimizing scripts.

7Implement script monitoring and timeout handling

In your application code, implement timeouts and error handling:

javascript
// 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.

Advanced notes

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.

Frequently asked questions

What does "BUSY" mean?
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.
How do I fix "BUSY"?
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.
What causes "BUSY"?
Lua script execution exceeds the lua-time-limit (default 5 seconds) Script contains expensive operations like scanning large key sets (SCAN with many keys) Script performs blocking operations or inefficient algorithms
Is the "BUSY" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading