To test an ERPNext backup restore, take a full backup with files, restore it with bench restore on a separate test server, and open the copy. A backup counts only once it has been restored somewhere else and checked. This guide covers what an ERPNext backup holds, why the site's encryption key matters, the exact bench commands, and what to check on the copy.
Short answer
Run bench --site {site} backup --with-files so the database and the attachments are both saved, and keep a copy of the site's site_config.json, which holds the encryption_key. Copy all of it off the server. On a separate test server with the same app versions, run bench --site {site} restore with --with-public-files and --with-private-files, put the old encryption_key back, stop emails and scheduled jobs on the copy, then log in and check real records.
I lead ERPNext, Frappe and open-source deployments at MithTech, a team of Frappe specialists in Bengaluru. The question that matters is not how to take a backup. It is whether the ones being taken would bring the business back.
Honest take: having backups and having a backup someone has restored are two different things.
What does an ERPNext backup contain?
Three parts, and a restore needs all three: the database, the files, and the site config. The database is a compressed SQL dump of every record. The files are two archives, public files and private files, which hold attachments, images and anything uploaded. The site config is a copy of site_config.json.
By default bench backup saves a compressed database dump under ./sites/{site}/private/backups, and its options set a separate path for each part, the config file included (bench backup reference). Frappe's site config page says the file "is backed up periodically along with the database backups in vanilla setups" (site config).
| Part | Saved by bench backup | Brought back by bench restore |
|---|---|---|
| Database dump | Always | The SQL_FILE_PATH argument (required) |
| Public files | Only with --with-files | --with-public-files |
| Private files | Only with --with-files | --with-private-files |
| Site config | A config file, path set by --backup-path-conf | No option; you copy the keys back by hand |
An ERPNext backup restore that skips any row gives you a copy that looks fine and is missing something.
Frappe Cloud backups have the same shape: its docs say every backup consists of a database backup, public files, private files and the site's config (Frappe Cloud backups).
Why does the restore need the encryption key?
Because Frappe encrypts the passwords a site stores with a key kept in that site's config. The site config reference describes encryption_key as the key used to encrypt passwords, created automatically on a fresh site, and says that "upon site restore, this key will have to be restored as well to be able to use existing passwords" (site config).
That is the trap. A new site on the test server gets a key of its own, and the bench restore reference lists no option for the config (bench restore reference). The copy keeps the test server's key until you copy the old one in.
A second key matters if you encrypt backups. With Encrypt Backup ticked in System Settings, Frappe encrypts the backup files with a backup_encryption_key from the site config. bench restore picks that key up from the site config, or you pass it with --backup-encryption-key (backup encryption guide). Lose it and the encrypted backups cannot be opened.
How do you take a complete backup?
Run the backup with files, then move it off the server. On a bench:
Add --compress to save the file archives as tgz instead of tar (bench backup reference). The backup also saves a copy of the site config. Keep all four files together.
Check what your automatic backups actually take. bench setup backups adds a cron job every six hours that runs bench --verbose --site all backup, with no --with-files (bench source). How many sets stay on the server is the backup_limit in System Settings (Frappe source). Either way they sit on the same disk as the site, and a backup that never leaves the server goes down with it.
On frappe_docker, bench commands run inside the backend container, for example docker-compose exec backend bench --site <site-name> backup --with-files. Its docs include a push_backup.py script that pushes the latest backup to S3, and say plainly that you can restore a backup only manually (frappe_docker site operations).
How do you restore it on a test server?
On a separate server, with the same app versions, restore the database and both file archives, then put the old key back. Never test on the live server. bench restore does not support downgrades, so the copy must not be on an older version than the backup (bench restore reference). The same versions are simplest.
Match the versions
Run bench version on the live server to list every app and its version, then build the test bench with the same apps and versions (bench commands). On frappe_docker, use the same image.
Create the site and copy the backup in
Create a site with bench new-site {site}. Copy the database file, the public and private file archives and the old site_config.json onto the test server. bench restore needs the database file on the local filesystem, and absolute paths work best; on frappe_docker that means inside the backend container.
Restore the database and both file archives
--admin-password sets a new Administrator password on the copy, so nobody needs the live one (bench restore reference).
Put the old encryption key back, and quieten the copy
Before anyone uses the copy, set three keys in its site_config.json, by hand or with bench --site {site} set-config: encryption_key (the old site's value), mute_emails to 1, which stops email sending, and pause_scheduler to 1, which pauses scheduled jobs (site config).
Migrate and log in
Run bench --site {site} migrate, which runs patches and syncs the schema with the code on the test bench. Then log in as Administrator.
What should you check after the restore?
Check that the copy holds your business as it stood at backup time, not just that a login page appears. A short list, done every time:
- Login works, as Administrator and as one ordinary user.
- The last transactions are there. Find the newest sales invoice, payment and journal entry on live at the backup time and open each on the copy.
- Attachments open. Open a private file, such as a purchase invoice scan, and a public one, such as an item image. This is what proves the file archives restored.
- A print format renders as a PDF, your own one if you have it.
- Stored passwords work. Open a settings form that holds a saved password, such as an email account. A wrong
encryption_keyshows here. - Emails are muted and the scheduler is paused on the copy.
- How long it took, from copying the files to the first login. That is your real recovery time.
Then delete the copy, or keep it locked down. It holds the same data as live.
How often should you test, and who signs it off?
At least once a quarter, after every major upgrade, and whenever the backup method changes. Each ERPNext backup restore test uses a recent backup, not one kept for the purpose. The sign-off is a short written note: which backup, restored where, when, how long it took, what was checked, and who checked it. Without the note, nobody after you can tell the test happened. If one person holds the method, the key and the server login, write the steps down where a deputy can find them. The ERPNext hardening checklist covers the rest of a self-run site, from access to updates.
Who takes the backups on each path?
On your own server you do all of it. Frappe Cloud takes and stores the backups for you. A managed host should do both and prove a restore. Frappe Cloud is the simplest path for the backups themselves: automated backups, with offsite copies on the plans that include them (Frappe Cloud backups). Its backup page describes no restore test, so on Frappe Cloud the test is still yours: download an offsite backup and restore it on a test bench as above.
| Your own server | Frappe Cloud | Run for you | |
|---|---|---|---|
| Who takes backups | You, or the bench cron job (database only) | Frappe, automatically | The host |
| Copies off the server | Yours to set up | Offsite copies on the plans that include them | The host; ask where the copies go |
| Restore test | Yours to schedule | Not described in Frappe's backup docs; yours | Ask how often one is restored |
| Encryption key | Yours to keep with the backups | The backup includes the site config | Stays yours |
For what else changes after go-live on each path, see who runs ERPNext after go-live. For the server bill on each, see the ERPNext hosting cost comparison.
Does the same test apply to other ERPs?
Yes. Whatever the ERP, a backup is proven only by restoring it to a copy and opening it. We support ERPNext, Tally, SAP Business One, Zoho and Odoo, and each has its own way to back up and restore. Where the ERP runs in its vendor's cloud, the same idea applies to the export you can take. The test is the same everywhere: restore away from the live system, open real records, and write down what you checked.
Should you test restores yourself, or have it done for you?
Test them yourself if someone on your team can run bench commands, has a spare server for the copy, and will do it every quarter; the steps above are all it takes. Have it done for you if nobody owns the test, or if a day without ERPNext would stop invoicing and dispatch.
Do it yourself if
You have someone at home with bench or frappe_docker, a test server to restore onto, a safe copy of site_config.json, and the habit of writing the sign-off note.
Have it run for you if
The backups have never been restored, nobody knows where the encryption key is kept, or the person who set up the server has left.
Under managed hosting we run ERPNext on one named server in your cloud account or ours, not a shared pool: nightly backups copied off the server, one restored on a schedule, every upgrade tried on a copy first, and the keys and the master login stay yours. We pick the region with you, an Indian region is the usual choice for Indian companies, and backups go to a second location you approve. It is a monthly fee for running it plus the server, quoted in writing after a call. If you leave, in your account the server is already yours; on ours you get a full backup, the code and the settings. If the server stays yours, support and AMC works on it as it runs and checks its backups. The self-hosting cost comparator sets either against doing it in-house.
Frequently asked questions
+Does bench backup include attachments?
Only with --with-files. Plain bench backup saves a compressed database dump, and the cron job that bench setup backups adds runs without --with-files. If attachments matter, and in most ERPNext sites they do, add a backup with files to your schedule and copy it off the server.
+Can I restore only the files from an ERPNext backup?
Not with bench restore. Its reference says there is no way to restore only files with that command, and the database file is the least it needs. Restore the whole site to a copy, then take what you need from there.
+Can I restore a backup onto an older ERPNext version?
No. The bench restore reference says downgrades are not supported for Frappe sites, and it prompts before going ahead if it detects one. Build the test bench on the same versions as live, which bench version lists.
+What happens if I lose the encryption_key?
The database and files still restore, but Frappe's docs say the key has to be restored with the site to use existing passwords. Plan on entering each stored password again, such as email account passwords. If backups are encrypted, losing the backup_encryption_key is worse: the backup files cannot be decrypted.
+Do Frappe Cloud backups need a restore test?
Yes, if you want proof. Frappe Cloud takes the backups and keeps offsite copies on the plans that include them, and each backup holds the database, both file sets and the site config. Its backup docs describe no restore test, so download one and restore it on a test bench now and then.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 29 October 2026
Worked with us? Leave a Google review