Find out why some pages won't migrate

Sample Situation

You have migrated a Confluence space that contains 3000 pages. Yet, when looking at the target site’s Site Pages library, you can only see 2900 pages. That’s 100 pages missing.

What’s up with those 100 missing pages? Why won’t they migrate?

What are possible root causes?

There are many reasons why pages fail to migrate. Some of them are temporary.

Here is a list of common issues:

• Connection Issues
  • when downloading content from Confluence, there was a service or connection issue
  • when creating a page in SharePoint Online, there was a service or connection issue and page or attachment creation failed
• Not enough Disk Space
  • there is not enough disk space for WikiTraccs to download all page attachments
• “Interesting” Page Content
  • a page contains content that WikiTraccs has never seen before and that it can’t handle well

WikiTraccs has mechanisms built-in to deal with some of those issues. For example, attachment upload and SharePoint page creation will be retried a couple of times to work around temporary connection issues. Missing disk space will cause the migration to be paused, until space is available again.

What to try first?

The first thing you should do is run the migration again, until the number of migrated pages stabilizes.

After the first migration run, 100 pages might be missing (for example due to unstable networking conditions). The second migration run might migrate another 50 pages. And the third migration run doesn’t change that.

Now what you are dealing with is the 50 pages that are still missing.

How to diagnose this?

The first thing we need is to look at the progress log files: Using progress log files to get insights.

Use the __30-aggregated-info progress log file to learn about the expected number of pages and the missing number of pages.

Use the __10-not-yet-migrated-pages progress log file to learn which pages are missing. This file contains page IDs that can be used to look up those pages in the common log files.

Take note that new progress log files are created with each migration run and that each space (or CQL selector) gets its own set of progress log files. So make sure to look at the most recent ones.

The ultimate tool to diagnosing why a page didn’t migrate are the common log files: Common log files.

Using the page IDs from the __10-not-yet-migrated-pages progress log file, we can look up corresponding log messages in the common log file(s) of a migration run.

Ultimately, the common log files should tell what was going on with those pages.

How to solve this?

Sometimes the common log files show something obvious, like a system being down, an authentication failing, or connection errors. This might help you inferring solutions.

But often it’s easier to send me the log files via email, for further diagnosis: [email protected].

Make sure to send the progress log files and also the common log files for a migration run.