# Restoring a Backup
Restoring Valkey backups is critical for disaster recovery, staging environment replication, or rolling back to a known good state. Elestio supports restoration via its web dashboard and manual methods using Docker Compose and command-line tools. This guide covers how to restore Valkey backups from RDB or AOF files, for both full and partial restore scenarios, and includes fixes for common errors during the process.
## **Restoring from a Backup via Terminal**
This method assumes you already have a backup file such as **dump.rdb** or **appendonly.aof**. Restoring involves stopping the container, replacing the data file(s), and restarting Valkey so it can load the new data at boot time.
##### **Stop the Valkey Container**
Cleanly stop the container to prevent data corruption:
```bash
docker-compose down
```
##### **Replace the Backup File**
Move the desired backup file into the volume directory that maps to the Valkey container’s **/data**.
**Example for RDB:**
```bash
cp ./backup_2025_06_24.rdb /opt/app/data/dump.rdb
```
Ensure your **docker-compose.yml** contains the correct volume mapping:
```yaml
volumes:
- ./data:/data
```
**For AOF-based persistence:**
```bash
cp ./appendonly_2025_06_24.aof /opt/app/data/appendonly.aof
```
##### **Restart Valkey**
Bring the container back up:
```bash
docker-compose up -d
```
Valkey will automatically load **dump.rdb** or **appendonly.aof** depending on its configuration in **valkey.conf** or Docker entrypoint.
## **Restoring via Docker Compose Terminal**
If you prefer working inside the container environment, you can directly inject the backup file into the Valkey container using Docker commands.
##### **Copy the Backup File into the Container**
**For RDB:**
```bash
docker cp ./backup_2025_06_24.rdb $(docker-compose ps -q valkey):/data/dump.rdb
```
**For AOF:**
```bash
docker cp ./appendonly_2025_06_24.aof $(docker-compose ps -q valkey):/data/appendonly.aof
```
##### **Restart the Valkey Container**
```bash
docker-compose restart valkey
```
Valkey will now reload the updated data file(s) during startup.
## **Partial Restores in Valkey**
Valkey, like Redis, does not support partial data restoration out of the box. However, workarounds exist to selectively restore key-value pairs or subsets of data.
##### **Restore Selected Keys via CLI**
If you’ve exported a list of keys and their values, you can restore them using a script with **valkey-cli**:
```bash
cat keys_to_restore.txt | while read key; do
value=$(cat dump.json | jq -r ".\"$key\"")
valkey-cli SET "$key" "$value"
done
```
This method is useful when working with pre-filtered exports in JSON, CSV, or key dumps.
##### **Restore from a Partial AOF**
If your backup is a trimmed-down AOF file (for example, created by filtering certain operations), Valkey will replay it entirely at startup:
- Replace the existing **appendonly.aof** file.
- Restart the container.
Valkey will process only the included operations, effectively performing a partial restore.
## **Common Errors & How to Fix Them**
Restoring Valkey may occasionally fail due to configuration mismatches, permission issues, or corrupted backup files. Below are common errors and their solutions.
**1. NOAUTH Authentication Required**
**Error:**
```bash
(error) NOAUTH Authentication required.
```
**Cause:** The Valkey instance requires authentication for any CLI interaction.
**Fix:**
```bash
valkey-cli -a yourpassword
```
**In scripts:**
```bash
valkey-cli -a "$VALKEY_PASSWORD" < restore_script.txt
```
**2. Valkey Fails to Start After Restore**
**Error:**
```bash
Fatal error loading the DB: Invalid RDB format
```
**Cause:** The backup file is corrupted or incompatible with the Valkey version.
**Fix:**
- Make sure the backup was created with the same or a compatible Valkey version.
- If necessary, downgrade or upgrade the container image to match the backup version.
**3. Data Not Restored**
**Cause:** Valkey is configured to use a different persistence method than the one you restored.
**Fix:**
Check your persistence mode in **valkey.conf** or Docker entry:
```bash
appendonly yes # for AOF
appendonly no # for RDB
```
Ensure the right file (**dump.rdb** or **appendonly.aof**) exists at **/data**.
**4. Permission Denied When Copying Files**
**Error:**
```bash
cp: cannot create regular file ‘/opt/app/data/dump.rdb’: Permission denied
```
**Fix:**
Use sudo if your shell user doesn’t have write access:
```bash
sudo cp ./backup_2025_06_24.rdb /opt/app/data/dump.rdb
```
Or adjust directory permissions as needed.
```bash
sudo chown $USER:$USER /opt/app/data
```