Troubleshooting XML backups that fail on restore
Seeing an error when creating or importing a site or space backup?
Exception while creating backup
Exception while importing backup
See instructions below
If you have problems importing 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
<confluence-home>/restoredirectory and import it from there.
- Are you trying to import into an earlier version of Confluence?
This is not possible. You can only import 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 imported 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 your username or password not recognised?
All user data was overwritten during the import 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 import into Confluence 5.10 or later. The username and password for the system administrator account will be
sysadmin. As soon as the import is complete, you must change this password. See Migrate from Confluence Cloud to Server.
- Did you download the export file on a Mac?
If you get an error saying that Confluence can't find the
exportDescriptor.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 import again.
Resolve Errors When Attempting To Restore An XML Backup
The errors may be caused by a slightly corrupt database. You will need to find the XML backup file entry that is violating the DB rules, modify the entry and recreate the XML backup:
- On the instance being restored, follow the instructions to disable batched updates (for simpler debugging), log SQL queries and log SQL queries with parameters at Enabling Detailed SQL Logging.
- Once all three changes have been made, restart Confluence.
- Attempt another restore.
- Once the restore fails, check your log files to find out what object could not be converted into XML format. For Confluence distribution users, check your Confluence install directory under the
/logs/and check both
catalina.outfile. The correct file will contain SQL debug output.
Scroll to the bottom of the file and identify the last error relating to a violation of the database constraint. For example:
This example indicates a row in your attachment table with ID = 38 that has a null title.
- Go to the server that the backup was created on. You must have a copy of the database from which the backup was created. If you do not have this, use a DBA tool to restore a manual backup of the database.
- Open a DBA tool and connect to the original database instance and scan the table names in the schema. You will have to modify a row in one of these tables.
- To work out which table, open
catalina.out, check the first line of the exception. To work out what table an object maps to in the database, here's a rough guide:
- Pages, blogposts, comments --> CONTENT table.
- attachments --> ATTACHMENTS table.
- To correct the example error, go to the attachment table and find that attachment object with id 38. This will have a a null title. Give a title using the other attachments titles as a guide. You may have a different error and should modify the database accordingly.
- Once the entry has been corrected, create the XML backup again.
- Import the backup into the new version.
- If the import succeeds, revert the changes made in your SQL logging to re-enable disable batched updates and turn off log SQL queries and log SQL queries with parameters.
- Restart Confluence.
Troubleshooting "Duplicate Entry" for key "cp_" or "cps_"
If you are encountering an error message such as:
This indicates that the XML export came from a version of Confluence with a corrupt permissions database, caused by some 3rd party plugin. This is an issue that was fixed when CONF-22123 was implemented in Confluence 3.5.2. The simplest workaround is to export the space again after upgrading the instance to 3.5.2 or above. If that is not an option, then either the export will need to be edited manually to remove the duplicate permission entries or the source instance will need to have the offending entries removed. The following SQL queries can be used to look for such entries:
Remove all matching entries and perform the export again.
Troubleshooting "Duplicate Key" related problems
If you are encountering an error message such as:
This indicates that the Primary Key constraint 'PK_OS_PROPERTYENTRY_314D4EA8' has duplicate entries in table 'OS_PROPERTYENTRY'.
You can locate the constraint key referring to 'PK_OS_PROPERTYENTRY_314D4EA8' in your table 'OS_PROPERTYENTRY' and locate any duplicate values in it and remove them, to ensure the "PRIMARY KEY" remains unique. An example query to list duplicate entries in the 'OS_PROPERTYENTRY' table is:
Troubleshooting "net.sf.hibernate.PropertyValueException: not-null" related problems
If you're receiving a message like:
This means there's an unexpected null value in a table. In the above example, the error is in the name column in the USERS table. We've also seen them in the ATTACHMENTS table.
Remove the row with the null value, redo the xml export, and reimport.
To Help Prevent this Issue from Recurring
- If you are using the embedded database, be aware that it is bundled for evaluation purposes and does not offer full transactional integrity in the event of sudden power loss, which is why an external database is recommended for production use. You should migrate to an external database.
- If you are using an older version of Confluence than the latest, you should consider upgrading at this point.
Was this helpful?
Thanks for your feedback!