Restore a Space or multiple Spaces
This page describes how to restore data from an XML backup into a new or existing Confluence site.
You can create a space backup in the Confluence administration console or in Space tools for single-space backups only.
However, to restore an XML space backup you'll need System Administrator permissions.
Before you start
- Identical space keys will cause issues. Make sure the spaces you plan to restore don’t have the same space keys as any spaces in the destination site; this will cause the task to fail.
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. This is pre-installed with your Confluence installation.
Check your backup is compatible to be restored
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.
If you are restoring a backup to a later version, it can be restored successfully.
If you are restoring a backup to an earlier version, this is not supported and your import may fail.
Restore (import) a space from Confluence Cloud
As the way users are managed is different in Confluence Cloud there are a few more considerations when restoring a space from Confluence Cloud into Confluence Data Center or Server.
See Import a space from Confluence Cloud for a step-by-step guide.
Restore (import) a space from Confluence Data Center or Server
We recommend performing a full backup of your database before restoring your XML space backup. Occasionally the space restore task may fail, and a backup will make it easier for you to roll back.
There are two ways to restore a space or multiple spaces – by uploading a file (local drive), or from a directory on your Confluence server (restore directory).
Uploading a file is only suitable for small spaces. For best results, we recommend restoring from the restore directory. A very large file may take quite some time to restore.
Upload a file
To upload and restore small spaces:
- Go to Administration > General Configuration > Backup and restore
- Select Restore site or spaces
- Under What do you want to restore?, select Spaces
- Under Restore from, select Local drive
- Under Select file, select Choose file and browse for your XML backup
- Select Upload and restore
- You will see a confirmation message
- Select Upload and restore once more
Restore from server
Restoring from the home directory is a reliable alternative for large spaces.
To restore a space from the home directory:
- Copy the XML backup to
<confluence-home>/restore/space.If you're not sure where this directory is located, see Confluence Home and other important directories. - Go to Administration > General Configuration > Backup and restore.
- Select Restore site or spaces
- Under What do you want to restore?, select Spaces
- Under Restore from, select Restore directory
- Under Select a file, type or browse for your space export file in the dropdown menu
- Select Restore
- You will see a confirmation message
- Select Restore now
Space indexing
As you restore a space or multiple spaces, they will be indexed in the same way page index usually happens. That is, records will be added to a queue to be indexed and there is a job that checks these records. Indexing will happen when the record is picked up by this job. For this reason, there may be a small delay before a user is able to see the space in the Space directory or search for content within the spaces restored.
Confluence doesn't do a full site re-index for space and multi-space restore.
Groups and permissions
Importing a space will not import any users or groups that may have been granted specific space permissions in your source Confluence site. This means that if any pages are restricted to these groups, you may not be able to see them until you recreate these groups in your destination site.
Canceled or failed space restore
If you cancel a space restore while it is “queued”, the task will simply be canceled and you will be shown the task details at that point.
If you need to cancel the space restore while it is "in progress", the data that has already been processed and imported will need to be cleaned up before you can restore the same spaces to the destination site. You can still restore other spaces or restore a site.
For example, if you attempted to restore Spaces with keys A, B, and C, but the space restore failed or was canceled after it had already started, you will still be able to restore the Space with key D, but you can’t restore Spaces with keys A, B, or C again until you’ve removed any partially imported data. See Clean up leftover space data from a failed space import to learn how to remove this data.
Troubleshooting
If you have problems importing a space, 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 backup file into the<confluence-home>/restore/spaceand restore it from there. - Are you trying to import into an earlier version of Confluence?
This is not possible. You can only restore a space into the same version or a later compatible version. - Does a space with the same space key already exist?
Space keys are unique, so if you already have a space with the same key, you'll need to delete the existing space before restoring the new one. - Is the import timing-out or causing out-of-memory errors?
If the space to be restored is very large, you may need to temporarily increase the memory available to Confluence. See How to fix out-of-memory errors by increasing available memory. - Did you download the export file on a Mac?
If you get an error saying that Confluence can't find theexportDescriptor.propertiesfile, 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 restore again. - Did your import fail? Sometimes restoring a space may fail because of invalid data. This can lead to data being left behind in your database. You'll need to clean up leftover space data from a failed space import before you attempt to restore the same spaces again.
- Do you have adequate disk space?
Confluence will need to make copies of the backup file being restored at various points during the restore process. Make sure you have enough disk space to temporarily accommodate multiple copies of the file.