Restore a Site

This page describes how to restore data from an XML backup into a new or existing Confluence site.

You need System Administrator permissions to do this.

Restoring a site backup will:

  • Overwrite all existing Confluence data in your database. Back up your database before you start, see Production Backup Strategy for recommended methods.
  • Log you out of Confluence. Make sure you know the login details contained in the file you're about to import.

Before you start

  • All content replaced. Importing a site will replace all your content and users. Make sure you have a copy of your database.
  • Selective space restoration not possible. You can't select a single space to restore from the entire site backup. Instead, you can manually back up a space or multiple spaces, and then restore that XML.
  • XML export files should not be used to upgrade Confluence. Upgrade Confluence by following Upgrading Confluence.
  • If you are migrating to Confluence Cloud, use the Confluence Cloud Migration Assistant app that is pre-installed with Confluence Data Center and Server.

  • Stop your Synchrony standalone cluster. If you use Confluence Data Center, you'll need to stop your Synchrony standalone cluster completely before you restore a site. Once the restore is complete, you can restart your Synchrony cluster. This is not required if you allow Confluence to manage Synchrony for you.

Check your backup is compatible

You can't restore a backup into an earlier version of Confluence. 

For example, if your XML backup was generated from Confluence 8.3, you can't import it into Confluence 7.19.


To check whether your backup can be successfully restored:

  • Check which Confluence version you are using in Administration  > General Configuration> System Information. The version will be listed next to Confluence Version.
  • Check which Confluence version your XML backup was generated from. See How to Determine XML Backup Confluence Version.

(tick) If you are restoring a backup to a later version, it can be restored successfully.

(error) If you are restoring a backup to an earlier version, this is not supported and your import may fail.

Restore (import) a site from an XML backup

There are two ways to restore a site: by uploading a file (local drive), or from a directory on your Confluence server (known as the 'restore directory').

Uploading a file is only suitable for small sites. For best results and larger sites, we recommend importing from the restore directory.

Upload a file

To upload and restore a small site:

  1. Go to Administration  > General Configuration > Backup and restore 
  2. Select Restore site or spaces
  3. Under What do you want to restore?, select Site
  4. Under Restore from, select Local drive
  5. Under Select file, select select XML zip and browse for your XML site export file
  6. Select Upload and restore
  7. You will see a confirmation message, read this carefully as your site will not be accessible and its contents will be completely overwritten once the task starts
  8. Select Upload and restore once more

Restore from server

To restore a site from the home directory: 

  1. Copy the XML backup to <confluence-home>/restore/site. If you're not sure where this directory is located, see Confluence Home and other important directories.
  2. Go to Administration  > General Configuration > Backup and restore
  3. Select Restore site or spaces
  4. Under What do you want to restore?, select Site
  5. Under Restore from, select Restore directory
  6. Under Select file, type or browse for your site export file in the dropdown menu
  7. Select Restore
  8. You will see a confirmation message, read this carefully as your site will not be accessible and its contents will be completely overwritten once the task starts
  9. Select Restore now

Site reindexing

A full site re-index will start when the site has been restored. The site restore task isn't finished until this re-indexing job is complete.

Canceled site restore

If you cancel a site restore while its status is “queued”, the task will simply be canceled and you will be shown the task details at that point.

If you cancel the restore while it is "in progress" and your site is inoperable, this could corrupt your instance since the overwrite will have already started. You will be required to restore from a database backup in order to revert the site back to its previous state.

Restore from a scheduled backup

Scheduled backups are saved in <confluence-home>/backups so you will need to retrieve the XML backup from the correct folder, then copy it to the restore directory, and follow the steps listed above in order to restore the site from the restore directory.

We don’t recommend uploading scheduled backups of large sites from your local drive to restore it.

Troubleshooting

If you have problems restoring a site, check out these hints. 

  • Is your file too large to upload? 
    This is a very common problem. It happens when the file can't be uploaded to the server in time. To avoid this problem, drop your export file into the <home-directory>/restore/site directory and restore it from there.
  • Are you trying to import into an earlier version of Confluence?
    This is not possible. You can only restore a site into the same version or a later compatible version. 
  • Is the import timing-out or causing out of memory errors? 
    If the site to be restored is large, you may need to temporarily increase the memory available to Confluence. See How to fix out of memory errors by increasing available memory
  • Is the import taking a very long time?
    The size of the entities.xml file provides an indication of the amount of entities such as pages, versions, and comments. A very large site may take quite some time to restore. You can check the size of this file by unzipping the export file. 
  • Is your username or password not recognized?
    All user data was overwritten during the restore process. You need to log in with a system administrator account from the site that was exported. If you don't know the password, you'll need to reset it from the database. See Restore Passwords To Recover Admin User Rights.
  • Is your site export from Confluence Cloud?
    You can only restore into Confluence 6.0 or later. The Cloud export does not include a system administrator account, so you will need to start Confluence in recovery mode, create a new system administrator account, and make it a member of the confluence-administrators group. See Restore Passwords To Recover Admin User Rights for more.
  • Did you download the export file on a Mac?
    If you get an error saying that Confluence can't find the exportDescriptor.properties file, chances are OS X has unzipped the backup for you and sent the original zipped file to the trash. You need to retrieve the original zip file from the trash and then try the import again. 
  • Restoring into a site with a Synchrony standalone cluster?
    You must stop your Synchrony cluster before commencing the site restore.  


Last modified on Feb 29, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.