Optimizely and third-party package compatibility breaking changes
This article covers known Optimizely and third-party package incompatibilities when upgrading to Content Management System (CMS 13) and provides guidance for handling them. These issues were identified during real-world upgrade testing.
📘 Note This list does not cover all third-party package compatibility issues. It catalogs compatibility for commonly used packages found in real-world implementations. It may not accurately reflect third-party compatibility after CMS 13 became generally available. Refer to https://nuget.optimizely.com/ for the most up-to-date compatibility.
Package compatibility summary
Package | CMS 12 Version | CMS 13 Status | Action Required |
|---|---|---|---|
EPiServer.Find.Cms | 16.x | Not compatible | Remove; no longer supported |
EPiServer.Forms | 5.10.x | Upgrade required | Upgrade to EPiServer.Forms 6.0.0 |
EPiServer.Cms.WelcomeIntegration.UI | 2.1.x | Not compatible | Replace with EPiServer.Cms.DamIntegration.UI |
Advanced.CMS.AdvancedReviews | 1.4.x | Not compatible | Remove; await update |
Geta.NotFoundHandler.Optimizely | 6.0.x | Not compatible | Remove; await update |
Geta.Optimizely.Sitemaps | 3.2.x | Not compatible | Remove; await update |
Geta.Optimizely.GenericLinks | 2.0.x | Not compatible | Remove; await update |
Geta.Optimizely.ContentTypeIcons | 2.1.x | Not compatible | Remove; await update |
Geta.Optimizely.Categories | 1.1.x | Not compatible | Remove; await update |
Gulla.Episerver.SqlStudio | 3.0.1 | Upgrade required | Upgrade to 3.0.2+ |
Stott.Optimizely.RobotsHandler | Various | Not compatible | Remove; await update |
Search & Navigation
Search & Navigation (EPiServer.Find.Cms) does not have a CMS 13-compatible version. Removal steps:
- Remove EPiServer.Find.Cms and any Search & Navigation related packages from your .csproj.
- Remove all Search & Navigation service registrations from Startup.cs (for example, services.AddFind()).
- Remove or replace any Search & Navigation dependent code (search implementations, indexing jobs).
- After removing Search & Navigation, you might encounter a missing Newtonsoft.Json reference. Add an explicit package reference: <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />.
📘 Note Search & Navigation removal may also require removing companion packages such as Geta.Optimizely.Categories.Find.
EPiServer.Forms
EPiServer.Forms (EPiServer.Forms 6.0.0) is compatible with CMS 13.
EPiServer.Cms.WelcomeIntegration.UI
The Welcome Integration and DAM UI package (2.1.x) references geolocation APIs that were moved to the EPiServer.Cms.DamIntegration.UI package in CMS 13.
You should remove the package reference and disable AddDAMUi() service registration, and install EPiServer.Cms.DamIntegration.UI (see Configure DAM Asset picker).
Advanced.CMS.AdvancedReviews
Advanced Reviews (1.4.x) fails because it references ServiceCollectionExtensions types that were moved to EPiServer.DependencyInjection.
You should remove the package and service registration. Await an updated version.
Geta.NotFoundHandler
Geta.NotFoundHandler (6.0.x) uses the SortIndex attribute property that was removed in CMS 13, causing a TypeLoadException at runtime.
You should remove the package references and service registrations. Await a CMS 13-compatible update.
Geta.Optimizely.Sitemaps
Geta.Optimizely.Sitemaps (3.2.x) has access modifier conflicts with CMS 13. The PropertySEOSitemaps property causes a TypeLoadException.
You should remove the package. Await a CMS 13-compatible update. Note that configuration properties such as SitemapOptions.EnableLanguageDropDownInAdmin were also removed.
Geta.Optimizely.GenericLinks
Geta.Optimizely.GenericLinks (2.0.x) causes a TypeLoadException due to PropertyLinkDataCollection access modifier conflicts with CMS 13's changes to PropertyLongString.
You should remove the package. Revert custom LinkDataCollection<CustomLinkData> properties to standard LinkItemCollection. Await a CMS 13-compatible update.
Geta.Optimizely.ContentTypeIcons
Geta.Optimizely.ContentTypeIcons (2.1.x) produces build errors against CMS 13.
You should remove the package reference, comment out service registrations, and remove [ContentTypeIcon] attributes from content type files. Await a CMS 13-compatible update.
Geta.Optimizely.Categories
Geta.Optimizely.Categories (1.1.x) fails because ContentReferenceListEditorDescriptor constructor signatures changed in CMS 13.
You should remove the package. Removal may leave orphaned content types (CategoryRoot, CategoryData) in the database. Consider adding stub classes to prevent "could not create instance" errors, or clean up the database directly.
Gulla.Episerver.SqlStudio
SqlStudio 3.0.1 references ISynchronizedObjectInstanceCache in a way that is incompatible with CMS 13.
You should upgrade to version 3.0.2 or later, which is CMS 13-compatible. Also ensure the service registration services.AddSqlStudio() is present. If the package is referenced, it must be registered or removed entirely.
Stott.Optimizely.RobotsHandler
The RobotsHandler package references types that are incompatible with CMS 13.
You should remove the package or await an updated version. If using the package, ensure services.AddRobotsHandler() and app.UseRobotsHandler() are both present, as missing service registrations cause authorization policy errors.
Orphaned scheduled jobs
After removing third-party packages, orphaned scheduled job registrations may remain in the database. These produce warnings at startup but are not blocking. Common orphaned jobs include those from Search & Navigation, Forms, NotFoundHandler, and Sitemaps.
You should delete orphaned job registrations within the admin UI under Settings > Scheduled Jobs, or leave them as non-blocking warnings.
Orphaned content types
Removing packages that registered content types (such as Geta.Optimizely.Categories) may leave orphaned content type definitions in the database. This can cause "could not create instance" errors.
Resolution options:
- Add stub classes that match the orphaned content type names to prevent instantiation errors.
- Clean up the orphaned content types directly in the database.
- Use the Admin UI to manage orphaned types if accessible.
General guidance for incompatible packages
When encountering a third-party package that is not compatible with CMS 13:
- Remove the package reference from your .csproj file.
- Remove or comment out service registrations in Startup.cs (for example, services.AddSomePackage() and app.UseSomePackage()).
- Remove using statements that reference the package's namespaces.
- Remove attributes and decorators from content types that reference the package.
- Check for transitive dependencies. Removing one package may expose missing references (such as Newtonsoft.Json after Search & Navigation removal).
- Document what was removed so you can re-enable packages when CMS 13-compatible versions are available.
- Watch for orphaned database artifacts such as scheduled jobs, content types, or database tables that remain after package removal.