Upgrading from XenForo 2.2 to 2.3 with add-ons installed

XenForo 2.3 changed enough under the hood that some add-ons built for 2.2 stop working, or break the pages they touch. The upgrade itself is routine. The work is in checking each add-on first and moving them to their 2.3 versions in the right order. Follow the steps below in order and there should be no surprises.

Why some 2.2 add-ons break on 2.3

The biggest change is JavaScript. XenForo 2.2 loaded the jQuery library on every page. XenForo 2.3 no longer does. Any add-on whose JavaScript relies on jQuery stops working: buttons do nothing, overlays never open, and the browser console shows an error such as "jQuery is not defined". Finding JavaScript errors.

Templates changed as well, so template modifications written for 2.2 may no longer find the text they look for. That is why many developers, including us, publish separate builds for 2.3.

Check every add-on before you start

1. List what you have installed: open Add-ons in the Admin CP, or run php cmd.php xf:addon-list.
2. For each add-on, check the developer's site for a version that supports XenForo 2.3. On D.C Style product pages, look at Compatibility.
3. Download the 2.3 versions now, so you have them ready. Download your add-ons.
4. If an add-on has no 2.3 version, decide what to do before you upgrade: find a replacement, or plan to uninstall it.

Several of our add-ons had a separate 2.2 build. Story 1.0.4, Thumbnail 1.0.5 Patch Level 6 and Thread Icon 1.0.1 Patch Level 1 were the last 2.2 builds, and the current releases need XenForo 2.3. Premium add-ons need an active update period to download the new version. How updates and renewals work.

The safe order

1. Back up the database and files. How to back up your forum.
2. Try it on a test copy first if you can. A private copy of your forum is covered by your license. What your license covers.
3. Close the board. Untick "Board is active" in Setup > Options > Board active. Administrators can still browse while it is closed.
4. Disable all add-ons. On the Add-ons page, click Disable all. XenForo remembers which ones it switched off.
5. Upgrade XenForo. Upload the XenForo 2.3 files over the old ones, then open yourforum.com/install/ in your browser. XenForo takes you to the upgrader. Over SSH, php cmd.php xf:upgrade does the same without time limits.
6. Upgrade your add-ons. Upload each add-on's 2.3 version and click Upgrade for it under Upgradeable add-ons. Disabled add-ons can be upgraded. How to upgrade an add-on.
7. Turn them back on. Click Enable at the top of the Add-ons page. XenForo lists the add-ons it disabled and lets you choose which to re-enable. Leave off any that have no 2.3 version.
8. Reopen the board once the checks below pass.

Tip: Enabling add-ons one or two at a time and checking the forum in between makes any problem easy to trace.

After the upgrade

• Look at Appearance > Outdated templates. Templates your style customized on 2.2 may need merging with the 2.3 versions. Template modification errors and outdated templates.
• Check Logs > Server error log for new errors. How to read it.
• Browse the pages each add-on touches, and open the browser console to catch JavaScript errors.
• If you use Cloudflare, purge its cache so visitors get the new JavaScript and CSS. Changes not showing?

Still stuck? Open a support ticket with your old and new XenForo versions, the add-on involved and the exact error. If you would like us to check your add-on list before you start, send that too.