How to fix BUSYKEY Target key name already exists in Redis

RedisINTERMEDIATEMEDIUMUpdated Dec 25, 2025· 157 views

The BUSYKEY error occurs when trying to use the RESTORE command to restore a key that already exists in your Redis database without using the REPLACE option. This prevents accidental data overwrites.

Quick fix

Fixes BUSYKEY

EXISTS mykey
  1. Check if the target key exists
  2. Inspect the existing key's content and expiration
  3. Delete the existing key if safe
  4. Use REPLACE option in RESTORE command
redis — error
EXISTS mykey
BUSYKEY Target key name already exists

What this error means

Redis raises the BUSYKEY error as a safety mechanism when you attempt to restore a serialized value to a key name that already exists in the database. By default, the RESTORE command does not overwrite existing keys to prevent unintended data loss. This error is distinct from other Redis key-related errors in that it specifically guards against attempting to write to an occupied key.

Typical symptoms

  • RESTORE commands fail with "BUSYKEY Target key name already exists" error
  • Data migration or backup restoration processes fail unexpectedly
  • Cluster import operations halt with BUSYKEY errors
  • Application logs show key conflict warnings during data persistence operations

Common causes

  1. Using RESTORE command on a key name that already exists in the database
  2. Attempting to import data into a Redis cluster where keys already exist
  3. Running backup restoration procedures without checking for key conflicts
  4. Multiple processes trying to restore data to the same key simultaneously
  5. Incomplete cleanup of old keys before attempting to restore new values

How to fix "BUSYKEY Target key name already exists"

1Check if the target key exists

Use the EXISTS command to verify whether the key is already in Redis:

redis
EXISTS mykey

If it returns 1, the key exists. If it returns 0, the key does not exist.

2Inspect the existing key's content and expiration

To understand what data is stored in the conflicting key:

redis
TYPE mykey
TTL mykey
GET mykey

Use GET for strings, HGETALL for hashes, LRANGE for lists, etc., based on the TYPE output. Check TTL to see if the key will expire naturally.

3Delete the existing key if safe

If you no longer need the data in the existing key, delete it before restoring:

redis
DEL mykey

Then proceed with your RESTORE command:

redis
RESTORE mykey 0 "<serialized-value>"
4Use REPLACE option in RESTORE command

The recommended solution is to use the REPLACE option (available in Redis 3.0+) to allow RESTORE to overwrite the existing key:

redis
RESTORE mykey 0 "<serialized-value>" REPLACE

This safely overwrites the target key without additional cleanup steps.

5For cluster import, use --cluster-replace flag

When importing data into a Redis cluster and encountering BUSYKEY errors, use the --cluster-replace flag:

bash
redis-cli --cluster import 127.0.0.1:6379 --cluster-from 127.0.0.1:6380 --cluster-replace

This allows existing keys to be overwritten during the import process.

6Review application logic for duplicate key creation

If BUSYKEY errors occur frequently in your application:

1. Check if multiple processes are writing to the same keys
2. Use RENAMENX instead of RENAME to avoid overwriting keys unintentionally
3. Add existence checks before RESTORE operations
4. Implement proper key naming schemes to avoid collisions
5. Use Lua scripts with atomic operations to ensure key safety

Advanced notes

The BUSYKEY error is fundamentally different from ERR key exists—BUSYKEY specifically applies to the RESTORE command and cluster operations. The REPLACE option in RESTORE (Redis 3.0+) executes an implicit DEL of the existing key before restoring, which is atomic and safe. However, if the existing key contains a large value, this operation may cause brief latency spikes. For high-throughput systems, consider using RENAME or RENAMENX as alternatives when appropriate. In Lua scripts and transactions, ensure you check for key existence before attempting RESTORE operations to prevent race conditions in concurrent environments.

Frequently asked questions

What does "BUSYKEY" mean?
Redis raises the BUSYKEY error as a safety mechanism when you attempt to restore a serialized value to a key name that already exists in the database. By default, the RESTORE command does not overwrite existing keys to prevent unintended data loss. This error is distinct from other Redis key-related errors in that it specifically guards against attempting to write to an occupied key.
How do I fix "BUSYKEY"?
The BUSYKEY error occurs when trying to use the RESTORE command to restore a key that already exists in your Redis database without using the REPLACE option. This prevents accidental data overwrites.
What causes "BUSYKEY"?
Using RESTORE command on a key name that already exists in the database Attempting to import data into a Redis cluster where keys already exist Running backup restoration procedures without checking for key conflicts
Is the "BUSYKEY" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading