Migration from Wiki Markup to XHTML-Based Storage Format

If you are upgrading to Confluence 4.0 or later from an older version (From Confluence 3.5.x or earler) then as part of the upgrade an automatic migration of your content will take place. This is a non-destructive process. Your existing content is not overwritten. Instead, the migration process will create a new version of each wiki markup page. The new version will use the new XHTML-based storage format, so that you can edit the page in the Confluence rich text editor.

In addition, if you are upgrading to Confluence 4.3 or later from an older version then as part of the upgrade an automatic migration of your page templates will take place. See Migration of Templates from Wiki Markup to XHTML-Based Storage Format.

Note: Even though the process is non-destructive, you must be sure to perform a backup of your database and home directory prior to starting the new version of Confluence, as we recommend for any Confluence upgrade.

Migration process

Depending on the size of your Confluence installation, the migration from wiki markup to the new XHTML-based storage format could prove time consuming. The duration of the migration is difficult to estimate; this is due to a number of site specific factors. As a rough guide, a test dataset we migrated was 130,000 pages, totalling approximately 700Mb, which took six minutes.

The following properties that can be modified to allow finer control over the migration process:





The number of concurrent worker threads migrating content



The number of items migrated in each batch of work



The comment associated with the newly migrated version of each piece of content

"Migrated to Confluence 4.0"

(For instructions on setting Confluence system properties see this document.)

Again, due to the large variability in Confluence installations it is hard to give specific recommendations for the above settings. One point to note though that both increasing batch size and the number of threads (or both) will increase the peak memory required for migration. If memory is an issue then as you increase one of these settings consider decreasing the other.

Another factor to be aware of if modifying these defaults is that of the cache settings employed in your site. The migration will quickly populate certain Confluence caches so be sure that if you have customised caches as described here that there is enough memory on the server for these caches should they reach maximum capacity.

Watching the migration logs during the upgrade

To monitor the progress of a site migration you should watch the output in the application log.

Typical logging progress will be shown by multiple log entries at the INFO level of the following format:

WikiToXhtmlMigrationThread-n - Migrated 2500 of 158432 pages, this batch migrated 500/500 without error

There may be a wide array of messages logged from each individual page but any errors are also collected for display in a single migration report once all content has been processed. Here is a typical example of such a report:

Wiki to XHTML Exception Report:
	0 settings values failed.
	0 PageTemplates failed.
	2 ContentEntityObjects failed.
Content Exceptions:
	1) Type: page, Id: 332, Title: Release Notes 1.0b3, Space: DOC - Confluence 4.0 Beta. Cause: com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro link is unknown.. Message: The macro link is unknown.
	2) Type: comment, Id: 6919, Title: null, Global Scope. Cause: com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro mymacro is unknown.. Message: The macro mymacro is unknown.

Each entry in the report will identify the content that caused migration exceptions as well as displaying the exceptions themselves.

In almost all cases any content reported as errored will have been migrated to the new  XHTML-based storage format, but will actually consist of wiki markup content wrapped within an XML 'unmigrated-wiki-markup' macro. This content will still be viewable in Confluence and editable within the new Confluence Editor.

However, in some cases a batch of content may actually have completely failed to migrated. This is most typically due to an unhandled exception causing a database transaction rollback. This would be reported in the log with a message like this:

Unable to start up Confluence. Fatal error during startup sequence: confluence.lifecycle.core:pluginframeworkdependentupgrades (Run all the upgrades that require the plugin framework to be available) - com.atlassian.confluence.content.render.xhtml.migration.exceptions.MigrationException: java.util.concurrent.ExecutionException: org.springframework.transaction.UnexpectedRollbackException: Transaction rolled back because it has been marked as rollback-only

Confluence provides no further report about this scenario and will also allow Confluence to restart as normal without retrying a migration. If a user tries to view any such unmigrated content they will see an exception similar to this:

java.lang.UnsupportedOperationException: The body of this ContentEntityObject ('Page Title') was 'WIKI' but was expected to be 'XHTML'

The solution is to ensure you manually re-run the site migration after the restart.

Re-running the migration – for content that completely failed the migration

A Confluence Administrator can restart the site migration if there was any content that failed migration (see previous section). Only the content that is still formatted in wiki markup will be migrated, so typically a re-migration will take less time than the original migration.

To manually re-run migration:

  1. Open this URL in your browser: <Confluence Address>/admin/force-upgrade.action
  2. Select wikiToXhtmlMigrationUpgradeTask in the Upgrade task to run dropdown list.
  3. Choose Force Upgrade.

Re-attempting the migration – for content in 'unmigrated-wiki-markup' macro

The previous section was about dealing with the exceptional circumstance where certain content was left completely unmigrated. The most common migration problem is that the content was migrated but remains formatted as wiki markup on the page, within the body of an 'unmigrated-wiki-markup' macro. Any content which is referenced in the migration report will be found in this state. This content is still viewable and editable but since it is wiki markup it cannot be edited using the full feature set of the rich text editor.

The most common reason for content to be in this state is that the page contains an unknown macro, or a macro that is not compatible with Confluence 4.x.

There are two possible fixes for this situation:

  1. Install a version of the macro that is compatible with Confluence 4.x. See Plugin Development Upgrade FAQ for 4.0 .
  2. Edit the page and remove the problematic macro.

Regardless of the solution you choose, you can then force a re-migration of all the content (including content in templates) that was left wrapped in an 'unmigrated-wiki-markup' macro. This feature is found at <Confluence Address>/admin/unmigratedcontent.action


We refer to the Confluence storage format as 'XHTML-based'. To be correct, we should call it XML, because the Confluence storage format does not comply with the XHTML definition. In particular, Confluence includes custom elements for macros and more. We're using the term 'XHTML-based' to indicate that there is a large proportion of HTML in the storage format.

Was this helpful?

Thanks for your feedback!

39 Archived comments

  1. User avatar

    Dick Visser

    I'm now at the point that I have:


    Confluence has detected that there are 23 pages with macros that are not yet Confluence 4+ compatible.

    Nice to know the number, but from here there is no way of knowing which pages need action (wink)

    Kind of stuck here now....

    16 Jan 2012
    1. User avatar

      Paul Biagio

      "If you are able to view the log output for confluence, you could set com.atlassian.confluence.content.render.xhtml.migration to ALL under <BASE URL>/admin/viewlog4j.action and then run the migration from <BASE URL>/admin/unmigratedwikicontent.action . The log will show you the page title, which is then somewhat easy to search for though Confluence. If you still have the old log files from when you first upgraded to 4.0, it includes the page ID along with the macro error, which is more useful for quick access to the page." - https://answers.atlassian.com/questions/15230/confluence-4-0-finding-pages-that-have-content-with-incompatible-upgraded-macros

      This solved my problem by showing page names in the logs.

      26 Feb 2015
  2. User avatar

    Mark Ellevsen

    We're in the same boat. Interestingly, also with 23 pages.

    Would really love to know how to identify the affected pages - ideas, anyone?

    18 Jan 2012
    1. User avatar

      David Corley

      There's a report generated in the Confluence logs at the end of the upgrade process showing all of the pages that were not upgradeable.

      23 is not too bad...Our test instance shows over 700 pages with issues...... (sad)

      19 Jan 2012
      1. User avatar


        Our instance shows 414 pages  (sad)

        04 Apr 2012
        1. User avatar

          Robert Ortner

          Confluence has detected that there are 3,593 pages with macros that are not yet Confluence 4+ compatible  (sad) 

          11 Apr 2012
          1. User avatar

            Rachel Dunlop

            Where can you see that information?

            22 Jan 2013
  3. User avatar

    Manuela Raschke

    Apparently we missed the report during the migration. But there are a number of pages which are not completely migrated. Is there a way to identify these pages?

    23 Jan 2012
    1. User avatar

      David Corley

      There should be an option to do a content re-migration from the administration section of Confluence. At the end of the content re-migration process, you should see a report output in the log.

      23 Jan 2012
      1. User avatar

        Rachel Dunlop

        Is there no way to see this without doing a re-migrate? Our ICT manager is (rightly) nervous about just running a re-migrate will-he, nill-he.

        22 Jan 2013
    1. User avatar

      Jennifer Cheung

      I usually do a search with the following string:

      That should return all the pages with the wiki markup wrapper (replace with the right macro name, if that isn't it). You can also search for this string in the BODYCONTENT table using SQL (using the right XHTML syntax of course, like '%<ac:macro...%').

      01 Mar 2013
  4. User avatar


    Have just issued a ticket for this as I'm still completely in the dark about which pages are affected...


    23 Jan 2012
    1. User avatar


      well this is not open ticket so cannot view the ticket

      04 Apr 2012
    1. User avatar

      Zachary Buckholz

      I'd also like to view that ticket, perhaps Atlassian can create a KB with the proper SQL syntax.

      We had a template for Spaces in 3.5.13 that had a 'table' macro that is now rendered across several hundred Spaces as Unknown macro: table


      06 Nov 2014
  5. User avatar

    Dick Visser

    Using the feedback from the above ticket, I ran these queries against my database, which showed the culprits:


    The second queries yielded a number of contentids. We run PostgreSQL, so I changed the query slightly to create a clickable HTML file by running this command (adjust the code to suit your site):


    psql confluence -Atc "SELECT '<a href=\"https://confluence.terena.org/pages/viewpage.action?pageId=' || contentid || '\">' || title || '</a><br />' FROM CONTENT WHERE CONTENTID IN (SELECT CONTENTID FROM bodycontent WHERE BODY LIKE '%unmigrated-wiki-markup%') AND PREVVER IS NULL AND CONTENTTYPE IN ('PAGE','BLOGPOST')" > unmigrated.html

    There were several issues here that screwed up the migration:

    • Pages containing copy/pasted software configuration files that looked something like:

      authenticate {
      	Auth-Type LDAP { ldap }


      but that didn't have proper tags around it. These pages probably were a problem before, but they only surfaced during the migration.
    • User-created macros that weren't migrated
    • Exotic plugins that created funky code and that had gone unnoticed during the upgrade

    The queries return also pages that are deleted. I didn't think it was reasonable to fix deleted pages, so I limited the result of the queries with CONTENT_STATUS != 'deleted' in the WHERE clause.
    After fixing all of them, and purging the bin to get rid of the offending deleted pages, I finally had the queries returning 0 result.
    However, the page /admin/unmigratedwikicontent.action page still says 9 pages left... 
    I don't know what that is, but as far as I'm concerned, the migration is done now (wink)

    06 Feb 2012
  6. User avatar


    I dont have any force upgrade option in my admin console...

    15 Feb 2012
  7. User avatar

    Dick Visser

    It's not shown on the admin console, you should manually paste this location after the wiki URL:



    15 Feb 2012
  8. User avatar

    Sebastian Freisinger

    I recently updated confluence from 3.5 to 4.1.9. Some content have failed migration.

    The manually Re-running Migration is successful with the following log:

    2012-04-24 13:59:54,536 INFO [http-80-1] [admin.actions.upgrade.ForceUpgradeAction] execute Upgrade task wikiToXhtmlMigrationUpgradeTask starting

    2012-04-24 13:59:54,536 INFO [http-80-1] [render.xhtml.migration.DefaultWikiToXhtmlSiteMigrator] migrateSite Completed migration of the site from wiki to XHTML with no errors.

    2012-04-24 13:59:54,536 INFO [http-80-1] [admin.actions.upgrade.ForceUpgradeAction] execute Upgrade task wikiToXhtmlMigrationUpgradeTask completed successfully in 0 seconds


    Nevertheless viewing previous versions of a page throw a java.lang.UnsupportedOperationException: The body of this ContentEntityObject ('xyz') was 'BodyType:WIKI' but was expected to be 'BodyType:XHTML'. This exception is caused by every previous page view. How can I migrate the whole version history? Has anybody else such a problem?


    24 Apr 2012
    1. User avatar


      I fixed the problem myself. An installed plugin (Page Approval Plugin) caused the error. Without it everything works well.


      27 Apr 2012
  9. User avatar

    Graham Hannington

    Does anyone want an XSLT stylesheet to convert macros (inherited from Confluence 3) into equivalent native Confluence XML?

    Some macros used in Confluence 3 wiki markup are now, arguably, obsolete; they could be replaced by equivalent native Confluence 4 XML.

    For example, if, in Confluence 3, you used the {table} macro and its related macros ({tr}, {td} etc.) from the Adaptavist Content Formatting Macros plugin, you might now wish to use the native (XHTML-based) Confluence XML table markup, and the corresponding support in the Confluence 4 rich text editor for editing tables, rather than editing multiple nested macro placeholders for {table} et al.

    My Confluence site is small, and we mostly kept to simple wiki markup for tables in Confluence 3, so this is not a problem that I am personally facing.

    But I do wonder: is this issue a pain for anyone out there? I hate to think that there are Confluence 4 users who are, in the rich text editor, editing tables that are represented by table macro placeholders, when they could be editing "native" tables.

    It occurs to me that I could relatively quickly develop an XSLT stylesheet to transform the <ac:macro> XML elements for {table} et al into the "native" XHTML-based <table> markup. And then perhaps wrap that XSLT stylesheet in some rudimentary user interface to make it easy to use. Or maybe there's already an existing solution to this? (I haven't looked very hard; like I say, it's not a problem that I am personally facing. I really am just responding to the unhappy thought I had that people might be editing tables as multiple nested macro placeholders in the Confluence 4 rich text editor.)

    I'm not quite sure how to measure this demand. Perhaps, send me an email? (I won't quote my address here, but I'm not difficult to find.) Or - it's just an idea - maybe "like" this comment? (A dozen likes would be enough to prompt me into action.)

    To clarify this offer: you can already convert "macro placeholder"-style table markup (described above) to "native" XHTML <table> markup simply by copying'n'pasting the rendered HTML (what you see when you view the page, rather than edit it) back into the rich text editor. But that method is only practical for piecemeal conversion (one table, or one page, at a time). You could use an XSLT stylesheet as the basis of a "batch" conversion process.

    01 Jun 2012
    1. User avatar

      Rachel Dunlop

      Is it possible to do something similar but with table-plus tables which have been dumped into wiki-markup macros after upgrading? We have squillions and our users aren't comfy using the markup (crazy folks!) to edit the tables. It has been suggested that we attempt to re-migrate but that seems awfully risky if a script could do it?

      22 Jan 2013
      1. User avatar

        Graham Hannington

        Bob Swift would be the best person to answer this, but I'll have a go.

        No and yes.

        No: it is not possible (okay, almost anything is possible; I guess I really mean "it is not feasible") to use what I offered (an XSLT stylesheet) to convert table-plus macros into "native" Confluence 4+ XML markup (with the tables in XHTML-like <table> markup rather than Confluence 3.x wiki markup). XSLT is not an ideal language for converting wiki markup into XML. (I'm not saying it's impossible, but there are better languages than XSLT for string manipulation.)

        Yes: I can at least offer some ideas for converting table-plus tables into "native" <table> markup. But the initial ideas that I'm going to present here are based on using the Confluence editor, not an automated conversion script. We can discuss the idea of automated scripts later, if you like.

        The table-plus macro offers features that are currently not available in Confluence 4 tables. Depending on the table-plus features that you use, you might decide - perhaps on a case-by-case basis - whether you want to keep using the table-plus macro (inside the "Wiki Markup" macro, <ac:macro ac:name="unmigrated-wiki-markup">) or discard the table-plus macro, and migrate its contents to native Confluence 4+ XML markup.

        For example, suppose you have a page that contains the following Wiki Markup macro (containing a table-plus macro). Here, I am deliberately showing the XML markup:

        You might decide that you can live without the features introduced by table-plus (such as auto total); you just want the table to be editable as a "native" table in Confluence.

        To do that:

        1. Select (click) the Wiki Markup macro in the editor (exactly how the editor indicates that the macro is selected might depend on your browser, but that's another story).
        2. Copy the selection to the clipboard (in Windows, press Ctrl+C).
        3. Select Insert > Wiki Markup (or press Shift+Ctrl+D).
        4. Paste (press Ctrl+V) the contents of the clipboard (the table-plus macro) into the Wiki Markup dialog.
        5. Delete the table-plus macro start and end tags, leaving only the table wiki markup.
        6. Click Insert.

        The table appears as a "native" Confluence table, replacing the Wiki Markup macro.

        I know that this is not a good solution for converting squillions of table-plus macros, but it is a relatively quick procedure if you decide, while editing a page, that you can live without a particular instance of a table-plus macro.

        Another possible solution might involve asking Bob to develop a native Confluence 4 version of the table-plus macro; that is, a wrapper for native Confluence 4 table markup (editable using the Confluence 4 editor). To which Bob (not wishing to put words in his mouth) might reasonably respond, "How much are you willing to pay?" (wink)

        22 Jan 2013
        1. User avatar


          Table Plugin for Confluence is already enabled and the automatic Confluence migration should handle it. This is the answers discussion on the topic: https://answers.atlassian.com/questions/126622/table-plus-content-was-all-dumped-into-wiki-markup-tags-on-upgrade .

          Regarding migrations: these occur on a regular basis automatically by Confluence whenever it sees new macros installed and un-migrated macros. There is nothing you normally need to do except perhaps monitor for migration errors in the log and/or restart Confluence to get other migrations going. You also need to ensure the xhtml enabled macros are enabled of course. In some cases they can be disabled on install. In UPM, expand out the modules associated with the plugin and make sure they are enabled. For my plugins, 3.x compatible modules have -legacy in the name, the rest are xhtml (Confluence 4.x) macros.

          22 Jan 2013
          1. User avatar

            Bob Swift [Bob Swift Atlassian Add-ons]

            Oops, wasn't logged in.

            22 Jan 2013
            1. User avatar

              Graham Hannington

              Thanks for stepping in with a real answer, Bob. (smile)

              23 Jan 2013
        1. User avatar

          Rachel Dunlop

          Hi Graham, wow thanks for the effort you put into your response! That's awesome information!

          However, what I failed to specify in my original question is that I'm wanting to migrate the "wiki-markup" table-plus tables to proper table-plus tables, for some reason they haven't migrated correctly!

          22 Jan 2013
  10. User avatar

    Dmitry Filnov


    When trying to upgrade from 3.5 to 4.x I get the following in my application log (after trying forced upgrade) - 

    2013-01-18 18:18:02,245 INFO [http-8080-2] [admin.actions.upgrade.ForceUpgradeAction] execute Upgrade task wikiToXhtmlMigrationUpgradeTask starting
    2013-01-18 18:18:02,334 INFO [http-8080-2] [render.xhtml.migration.DefaultWikiToXhtmlSiteMigrator] migrateSite Completed migration of the site from wiki to XHTML with no errors.
    2013-01-18 18:18:02,336 INFO [http-8080-2] [admin.actions.upgrade.ForceUpgradeAction] execute Upgrade task wikiToXhtmlMigrationUpgradeTask completed successfully in 0 seconds

    Nothing is done on the first start of 4.x. And the forced upgrade doesn't show any stats on what has been updated. And, the worst part, nothing is upgraded. 

    When I open any page it says "Error: The XML content could not be parsed" and so on. The database still has old, unchanged content. 

    Any ideas?

    18 Jan 2013
      1. User avatar

        Dmitry Filnov

        You rock! Thank you. Worked for me too. 


        25 Jan 2013
  11. User avatar


    I wish there were a way to say "please retry migration of THIS PAGE"... Have I missed something?

    28 Mar 2013
    1. User avatar

      Paul Curren

      There is no way of doing this at the moment. However it would be possible to implement it. Could you explain a little about your full use case e.g. have you tried to fix something on the individual page and now you want to see if it is "migrate-able"?

      01 Apr 2013
  12. User avatar


    Well, at least I didn't loose any pages, but it hasn't resolved my issue. I simply can not Edit or Create any new Pages.

    04 Jun 2013
  13. User avatar

    Application Services

    Below is an SQL that I used to list the page names for pages that have unmigrated content:

    15 Aug 2013
  14. User avatar

    Jeff Shipley

    Is it possible to disable wiki to xhtml migration until after the new version of Confluence is running with all plugins updated and licensed (in the case of some once-free but no longer plugins)?

    25 Sep 2013
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      Hi Jeff, I think you would be best asking Support whether this is possible, and to get some advice about upgrading in your specific situation. http://support.atlassian.com/

      25 Sep 2013
  15. User avatar

    Matthias Oesterheld

    I'm in the process of upgrading from 3.2 to 5.3. I upgraded from 3.2 to 3.5 to 4.3 to 5.3.

    I now have 233 pages with unmigrated-wiki content. Unfortunately there is no /admin/unmigratedwikicontent.action in 5.3, I guess. Is there any way to update content with incompatible macros in 5.3? Otherwise I'd have to do the update to 4.3 once again, update all the plugins in 4.3, do the update content, update to 5.3 and update all the plugins again. Not something to look forward to (sad)

    20 Nov 2013
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      Hi Matthias, the file has been renamed.  You can now access this from confluence_base_url/admin/unmigratedcontent.action.  I have updated the docs above.  Sorry about the oversight. 

      24 Nov 2013
  16. User avatar

    Sergei Dorogin


    How can I upgrade my Confluence 3.1.2 to the latest Confluence (5.5 or the like) ? 

    26 May 2014
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      Hi Sergei, you can find information on the best upgrade path from Confluence 3.1 on this page Upgrading Confluence.  If you have questions or concerns you can also contact Support for assistance in planning your upgrade. 

      26 May 2014
Powered by Confluence and Scroll Viewport