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:

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:

cp ./backup_2025_06_24.rdb /opt/app/data/dump.rdb

Ensure your docker-compose.yml contains the correct volume mapping:

volumes:
  - ./data:/data

For AOF-based persistence:

cp ./appendonly_2025_06_24.aof /opt/app/data/appendonly.aof

Restart Valkey

Bring the container back up:

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:

docker cp ./backup_2025_06_24.rdb $(docker-compose ps -q valkey):/data/dump.rdb

For AOF:

docker cp ./appendonly_2025_06_24.aof $(docker-compose ps -q valkey):/data/appendonly.aof

Restart the Valkey Container

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:

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:

(error) NOAUTH Authentication required.

Cause: The Valkey instance requires authentication for any CLI interaction.

Fix:

valkey-cli -a yourpassword

In scripts:

valkey-cli -a "$VALKEY_PASSWORD" < restore_script.txt

2. Valkey Fails to Start After Restore

Error:

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:

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:

cp: cannot create regular file ‘/opt/app/data/dump.rdb’: Permission denied

Fix:

Use sudo if your shell user doesn’t have write access:

sudo cp ./backup_2025_06_24.rdb /opt/app/data/dump.rdb

Or adjust directory permissions as needed.

sudo chown $USER:$USER /opt/app/data