About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.
Nextcloud looks like a file server, so it is tempting to back it up like one by copying the files. That copy may be useless on its own. Nextcloud keeps file names, shares and folder structure in its database, its configuration holds values that cannot be regenerated, and with encryption switched on, the files cannot be read without keys held elsewhere on the server.
This guide follows the Nextcloud administration manual to explain what must be backed up together, how to keep the copies consistent, and what to expect when a backup is restored to a server that users' devices have already moved past.
Why it matters
Nextcloud often becomes the place a business keeps its working documents, and its desktop and mobile clients keep copies in step on every device. A failed restore can do more than lose data. Devices may sync in unexpected directions, or files may show in the interface but refuse to open.
How it works
The parts of a Nextcloud server
The backup page lists "five main things you need to retain":
- "The config folder"
- "The custom apps folder (only if you have custom apps installed)"
- "The data folder"
- "The theme folder"
- "The database"
The restore page is blunter: "You must have the database, data directory, and configuration files. You cannot complete restoration without all three."
What each part holds (our reading, from the pages cited):
- Configuration (
config/config.php) holds the database connection, the data folder location, trusted host names and, importantly, values generated at install time. The migration page says "The secret and instanceid values are generated once at install time and tied to all encrypted data and user sessions. Do not change or regenerate them." - The data folder holds file contents and, with server-side encryption, the encryption keys.
- The database holds what makes those files meaningful. For one storage layout the manual is explicit: with object storage as primary storage, "All metadata (filenames, directory structures, etc) is stored in Nextcloud and not in the object store. The metadata is only stored in the database and the object store only holds the file content by unique identifier."
Keeping the parts consistent
The parts must come from the same moment. The backup page uses maintenance mode for this: it "locks the sessions of logged-in users and prevents new logins in order to prevent inconsistencies of your data."
With maintenance mode on, the manual says to copy the configuration, data and theme folders "to a location outside your Nextcloud environment", or copy the whole installation including the data folder. It then dumps the database. For MariaDB and MySQL its examples use --single-transaction. Where full Unicode support is enabled ("needed for emoji"), it adds --default-character-set=utf8mb4. It notes that "MariaDB is the recommended database engine."
Maintenance mode is part of the documented consistency procedure, not proof that every background worker, integration or external storage writer is quiescent. Identify and control all writers for the capture window. A storage snapshot also needs a supported database-consistency method and coordination across every data location; maintenance mode alone does not establish that. Copying the data folder while users are active, then dumping the database later, risks a database that refers to files the copy does not have, or the reverse.
Our recommendation: also keep a record of the Nextcloud version, the PHP version and the database version with each backup. The migration page asks that the new server's PHP "matches Nextcloud supported configuration", and a restore is far simpler on matching versions.
Encryption keys and the instance secret
If server-side encryption is enabled, the keys are part of the backup. The encryption configuration page says, under its heading on backups, that keys are stored in data/<user>/files_encryption ("per-user keys") and data/files_encryption ("system-wide/external storage keys").
The same page warns: "Losing encryption keys or your instance secret results in permanent data loss."
Our reading: a backup of the data folder normally includes the keys, because they sit inside it. A backup that excludes some folders to save space, or that restores user files without the matching key folders, can leave files permanently unreadable. The instance secret lives in config.php, so a configuration backup is as important as the data. Verify the configured key-storage location rather than assuming every installation uses the default. Client-side end-to-end encryption has separate key requirements and is outside this server-side encryption discussion. These files are sensitive, so store and encrypt them accordingly.
The page also explains a limit that affects recovery planning. Recovery keys "are only available in per-user key mode (not the default master key mode)". In per-user mode, "If a user loses their password, their files are unrecoverable unless a recovery key is enabled". Users must also opt in in their personal settings.
Two encryption operations carry the manual's own warning, "Make sure you have backups before running": encrypting all existing files, and decrypting all files. Our recommendation: take and test a full backup immediately before either.
Object storage as primary storage
Some installations keep file contents in an object store, not on the server's disk. The primary storage page says the backup strategy "needs to incorporate this". The files "are also no longer accessible by simply bypassing your Nextcloud server and accessing your object store directly."
It also says Nextcloud "requires exclusive access over the bucket being used". And it warns that configuring a primary object store on an existing instance "will make all existing files on the instance inaccessible."
Our reading: with object storage, the bucket and the database are a matched pair. A bucket restored without the database from the same moment is a collection of unnamed objects. Versioning or object-lock features on the bucket can protect the content, but only alongside matching database backups.
What the restore involves
The restore page expects configuration, data, theme and database contents to be restored as a matched set. Its database procedure replaces existing tables, which makes destination selection a critical prerequisite. Plan a separate empty restore database instead of treating deletion of the existing one as a routine first step.
That step destroys whatever is currently in the database. Our recommendations: restore onto a new server or a new, empty database wherever possible, and keep the damaged installation untouched until the restored one is confirmed working. Where an in-place restore is unavoidable, first take a fresh copy of the current database and folders, even if they are damaged.
The migration page, which describes a related process, adds checks that apply equally to a restore on new hardware:
- Install the same optional services first (Redis or Memcached, object storage, LDAP, mail, full-text search). The page warns that failing to do so may cause errors, giving a Redis "server went away" message as its example, or connection failures at startup.
- Keep the data folder path the same. Changing it "might cause a corruption of relations in the database and is not supported."
- Keep file timestamps when copying, "otherwise the clients will re-download all the files".
- Start in maintenance mode, check the logs, and only then let users back in.
Checking a restore before users return
The migration page describes a careful order for bringing a moved server online, and it suits a restore just as well. While Nextcloud is still in maintenance mode, and before users are pointed at it, the page says to start the database and web server, "point your web browser to the migrated Nextcloud instance" and "Confirm that you see the maintenance mode notice, that a logfile entry is written by both the Web server and Nextcloud and that no error messages occur." Only then does it take Nextcloud out of maintenance mode, sign in as an administrator and "confirm normal function".
Our recommendations for the checks to add on a restored server:
- Open a sample of files from several users, including large files and, where encryption is on, files from different key folders.
- Check that shares, including links shared outside the business, still open.
- Compare file counts and storage used against figures recorded at backup time.
- Sign in as an ordinary user from a test device before opening the server to everyone.
- Keep the old installation available until these checks pass, as the migration page advises for its own process: "At NO TIME any changes to the ORIGINAL system are required EXCEPT putting Nextcloud into maintenance mode."
Sync clients after restoring an older backup
Client reconnection needs its own recovery decision. The restore page explains: "By default the Nextcloud server is considered the authoritative source for the data." If the restored backup is older than the copies on users' devices, "the state of the clients may be more up to date than the state of the server."
For that case the manual says to run the maintenance:data-fingerprint command afterwards. It "changes the logic of the synchronisation algorithm to try and recover as much data as possible. Files missing on the server are therefore recovered from the clients and in case of different content the users will be asked."
It notes limits: the command "can cause conflict dialogues and difficulties deleting files on the client. Therefore it's only recommended to prevent dataloss if the backup was outdated." With several application servers, the configuration must be synced "so that the updated data-fingerprint is applied on all instances." The migration page adds that if the original configuration already had a data fingerprint set, the command should also be run on the new system.
Our reading: whether to use it is a business decision. If the restore was needed because of bad changes on the server (for example, files encrypted by ransomware and then synced), pulling client copies back may reintroduce the problem. Check the state of client devices before deciding.
What to choose and why
These are our recommendations, drawn from the manual.
- Back up all parts together: configuration, data folder, database, theme and any custom apps. Follow the documented maintenance procedure and coordinate database, background writers and external storage capture.
- Protect
config.phpand the key folders as you would passwords: encrypted, access-controlled and kept off the server. - Record versions of Nextcloud, PHP and the database with each backup.
- Treat object storage and database as one unit when object storage is primary storage.
- Restore to a new server or empty database first; leave the original untouched.
- Match paths and services on the restore target.
- Decide in advance when you will use the data fingerprint command after an older restore.
- Back up before encrypting or decrypting all files.
- Test a full restore regularly, including opening encrypted files and signing in as a normal user.
Risks and limits
- Partial restores fail: the manual says restore is not possible without database, data and configuration.
- Lost keys or a lost instance secret mean permanent data loss with server-side encryption.
- The documented restore drops the existing database; restore to a new database where possible.
- Older restores interact with sync clients; the fingerprint command has side effects.
- Changing the data folder path is not supported.
- Packaged editions (AIO, Snap) differ; follow their own guides.
- Nothing here was run. Behaviour is quoted from the manual for planning; rehearse on a separate server.
Sources
- Nextcloud Administration Manual, Backup: https://docs.nextcloud.com/server/latest/admin_manual/maintenance/backup.html
- Nextcloud Administration Manual, Restoring backup: https://docs.nextcloud.com/server/latest/admin_manual/maintenance/restore.html
- Nextcloud Administration Manual, Migrating to a different server: https://docs.nextcloud.com/server/latest/admin_manual/maintenance/migrating.html
- Nextcloud Administration Manual, Server-side encryption configuration: https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html
- Nextcloud Administration Manual, Configuring object storage as primary storage: https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/primary_storage.html
This article was originally published on .