Upgrade from legacy versions
To upgrade Optimizely Content Management System (CMS), you need to upgrade from one major version to the next, step by step. This page gathers the relevant links needed to do so, if you are on the earlier versions 4, 5, or 6. From version 7, see the Upgrade CMS sections.
This link collection was put together by Arild Henrichsen.
Upgrade from MS 4 to CMS 5
If your existing site is pre-4.62:
- Upgrade from 4.x to 4.61: <http://world.episerver.com/Articles/Items/Experiences-from-migrating-to-EPiServer-461-and-ASPNET-20/>
If your existing site is 4.62:
See the following documentation:
- Migrating from 4.62 to CMS 5 R2 (using Migration Tool 1.1.0.38):
<http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-5/EPiServer-CMS-5-R2/EPiServer-CMS-Migration-Tool-11/>
1. Download and install .NET 3.5 SP1
2. Download and install CMS 5 R2
- (Don't install site yet).
3. Obtain a valid CMS 5 license
4. Prepare existing 4.62 site (source):
- Back up existing site and database.
- Verify that database connection string is correct.
- Verify that paths to filesystem (upload) and admin/edit UI are correct.
- Verify that the site is browseable, login works and it has a valid license.
5. Install a new CMS 5 R2 site (target) using CMS Manager:
- Must use new database, but a pre-existing database user account can be used.
- Supply a valid license.
- Do not install Public/Demo Templates.
- Verify that NETWORK SERVICE and IUSR_<hostname> accounts have read/write access to the web site root.
- Verify that the site is browseable.
📘 Note If using IIS 5 (e.g. WinXP), only one site may be running at a time. In this case, stop the old 4.62 site and start the new CMS 5 R2 site before continuing.
6. Install and run the Migration Tool 1.1.0.38:
- Specify source and target site, and their respective licenses.
- Migration is finished.
7. Copy the files from the 4.62 site over to the CMS 5 R2:
- Templates folder, language files, scripts folders, any plugins or custom properties folders.
- Filesystem (upload) will be converted and copied automatically during the migration.
- Merge differences between the 4.62 site web.config and the CMS 5 R2 site web.config (applicationSettings, upload path, UI path and so on).
8. Handle breaking changes:
- Rewrite any code that no longer compiles (see Breaking Changes documentation).
- Redeploy files and retry.

9. Test CMS 5 R2 site:

- Verify that site is browseable and that admin/edit login works.
- Verify that the filesystem is intact.
Additional references for CMS 4/5:
- Migrate from 4.62 to CMS 5 R1 (manually): http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-5/EPiServer-CMS-R1/Migrating-to-EPiServer-CMS/
- Migrate from 4.62 to CMS 5 R1 SP2 (using Migration Tool RC1): http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-5/EPiServer-CMS-SP2/Migration-Tool-RC1/
- Migrate to 4.61 and ASP.NET 2.0: http://world.episerver.com/Articles/Items/Experiences-from-migrating-to-EPiServer-461-and-ASPNET-20/
Challenges when moving from CMS 4 to CMS 5:
Rewrite code to handle breaking changes:
- http://world.episerver.com/Documentation/Items/Release-Notes/EPiServer-CMS/Release-Notes---EPiServer-CMS-5-R1/Breaking-Changes-in-EPiServer-CMS-5/ (also applies to CMS 5 R2)
Rewrite from ContentFramework to ASP.NET 2.0 MasterPages:
- http://world.episerver.com/Articles/Items/Experiences-from-migrating-to-EPiServer-461-and-ASPNET-20/
Replace EPiFields with Dynamic Content:
- http://world.episerver.com/Articles/Items/Farewell-EPiFields-Hello-Dynamic-Content/
Handle changes in the configuration files:
- http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-5/EPiServer-CMS-R1/Configuration-in-EPiServer-CMS/
- http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-5/EPiServer-CMS-5-R2/Changes-Between-IIS6-and-IIS7/
Implement the ASP.NET 2.0 Membership/Role Provider system:
- http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-5/EPiServer-CMS-R1/Authentication-and-Authorization-in-EPiServer-CMS-5/
Changes to the filesystem:
- http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-5/EPiServer-CMS-5-R2/Virtual-Path-Providers-in-EPiServer-CMS-5/
Troubleshoot - CMS 4 to 5
_Errors during EPiServer 4 installation/configuration:
ERROR: Cannot install files: The installation failed, and the rollback has been performed.[The name is already in use as either a service name or a service display name] CAUSE: A newer version of the EPiServer Scheduler service is already installed on the web server. Installing EPiServer 5.x on a system where EPiServer 4.x is installed is OK, but the other way around causes problems. SOLUTION: Go to Administrative Tools > Services > Stop and disable the "EPiServer Scheduler service". OPTIONAL SOLUTION:
- Control Panel > Add/Remove Programs > Uninstall the EPiServer CMS 5 Scheduler service.
- Reinstall EPiServer 4.x and EPiServer 4 Shared Components.
- Run migration, then reinstall EPiServer 5.x and EPiServer 5 Shared Components.
For more information see: https://world.episerver.com/blogs/Magnus-Rahl/Dates/2009/1/Problems-installing-EPiServer-4x-with-newer-versions-of-EPiServer-and-NET-present/
ERROR: System.Web.Services.Protocols.SoapException: Server was unable to process request. ---> System.NullReferenceException: Object reference not set to an instance of an object.
at LicenseRegistry.LicenseCreator.CreateLicense(License license) at LicenseRegistry.DataAbstraction.License.CreateLicenseFile() at ProductUpdate.InstallUnit..ctor(Int32 licenseNumber, String licensedCompany) in C:\LicenseRegistry\Production\ProductUpdate\InstallUnit.cs:line 30 at ProductUpdate.UpdateManager.AddLicense(Product prod, InstallUnit[] units) in C:\LicenseRegistry\Production\ProductUpdate\UpdateManager.asmx.cs:line 132 at ProductUpdate.UpdateManager.RequestInstall(Product product) in C:\LicenseRegistry\Production\ProductUpdate\UpdateManager.asmx.cs:line 122
CAUSE: When installing EPiServer 4.62B using online package, there is a known problem with the licensing system (seems the installer tries to generate/validate a license even though a license file has been supplied). SOLUTION: Use EPiServer Manager to create an offline installation package, and install from that instead (still using EPiServer Manager).
ERROR: System.Security.Cryptography.CryptographicException: Bad Data CAUSE: Web.config is encrypted, containing lines with values that could not be decrypted (was encrypted on another server - encryption is partly based on unique machine keys). SOLUTION: Replace the values in lines containing "ENCRYPTED" with plain-text values (can be found using EPiServer Manager on the server where the web.config was originally encypted, or insert values matching the new server).
Errors during migration from 4.x:
ERROR: Failed to register ASP.NET client scripts on this site[The system cannot find the file specified] Cause: Migration Tool is dependent on .NET 2.0 and is conflicted because .NET 3.0 or higher is installed on the system. Solution: Temporarily move or rename the following folders:
- C:\WINDOWS\Microsoft.NET\Framework\v3.0
- C:\WINDOWS\Microsoft.NET\Framework\v3.5 then retry the Migration Tool.
ERROR: Cannot find Stored Procedure "dbo.aspnet_CheckSchemaVersion": SOLUTION: Perform the following steps:
- Locate C:\\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_regsql.exe.
- Use the 4.62 database as command line argument and run with default settings.
- Restart SQL Server.
- dbo.aspnet_CheckSchemaVersion should now be found in the database.
Move from CMS 5 to CMS 6 R1
See to the following documentation:
- Upgrade a CMS 5 R2 SP2 site to CMS 6 R1http://world.episerver.com/Blogs/Joe-Bianco/Dates/2010/3/How-to-Upgrade-an-EPiServer-CMS-5-Site-to-CMS-6/
1. Download and install CMS 6 R1
2. Obtain a valid CMS 6 license
3. Upgrade the existing CMS 5 site using Deployment Center:
- Deployment Center > EPiServer CMS > Version 6.0.530.0 > Upgrade Site with SQL Server database.
- From the list, select the CMS 5 site you want to upgrade
- Click Upgrade to start the process
- On completion, close Deployment Center.
4. Install new CMS 6 license
5. Test the new CMS 6 site:
- Verify that the site is browseable and that admin/edit login works.
- Verify that file system is intact.
Challenges when moving from CMS 5 to CMS 6:
Handle breaking changes:
Web.config being split into multiple configuration files:
- http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-6/EPiServer-CMS-60/Configuration/
XForms being converted to the new Dynamic Data Store:
- http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-6/EPiServer-CMS-60/Dynamic-Data-Store/
- http://world.episerver.com/Documentation/Items/Tech-Notes/EPiServer-CMS-6/EPiServer-CMS-60/XForms/
Path to admin/edit view changed because of Online Center:
- http://world.episerver.com/Articles/Items/Streamline-Your-Daily-Work-with-EPiServer-CMS-6/
Additional references for CMS 5 / 6:
Upgrade from CMS 5 R2 to CMS 6 RC1:

- http://world.episerver.com/Blogs/Per-Bjurstrom/Archive/2009/12/Upgrading-to-CMS-6-RC1/
Move from CMS 6 R1 to 6 R2
See the following documentation:
- Upgrade an CMS 6 R1 site to CMS 6 R2:`http://world.episerver.com/Blogs/Joe-Bianco/Dates/2010/3/How-to-Upgrade-an-EPiServer-CMS-5-Site-to-CMS-6/
1. Download and install CMS 6 R2
- Always download the installer directly from Episerver World, to ensure you have the very latest version (with all the patches and bugfixes included).
2. Obtain a valid CMS 6 R2 license
3. Upgrade the existing CMS 6 R1 site using Deployment Center:
- Deployment Center > EPiServer CMS > Version 6.1.379.0 > Upgrade Site with SQL Server database.
- From the list, select the CMS 6 R1 site you want to upgrade.
- Click Upgrade to start the process.
- On completion, close Deployment Center.
4. Install new CMS 6 license
5. Test the new CMS 6 site:
- Verify that the site is browseable and that admin/edit login works.
- Verify that file system is intact.
Troubleshoot - CMS 6 R1 to 6 R2
Upgrade Xforms fails:
Blank page references in "Fetch-data" function:
Upgrade CMS 6 R1 sites that run .NET 4:
Issues when upgrading to CMS 6 R2:
IE11 incompatibility issues patch: