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

Search & Navigation

Search & Navigation (EPiServer.Find.Cms) does not have a CMS 13-compatible version. Removal steps:

1. Remove EPiServer.Find.Cms and any Search & Navigation related packages from your .csproj.
2. Remove all Search & Navigation service registrations from Startup.cs (for example, services.AddFind()).
3. Remove or replace any Search & Navigation dependent code (search implementations, indexing jobs).
4. 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 5.10.x) is not compatible with CMS 13. The package references IBlobFactory and geolocation APIs that were moved or removed.

You should remove all Forms packages and related service registrations. Await a CMS 13-compatible release.

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:

1. Add stub classes that match the orphaned content type names to prevent instantiation errors.
2. Clean up the orphaned content types directly in the database.
3. 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:

1. Remove the package reference from your .csproj file.
2. Remove or comment out service registrations in Startup.cs (for example, services.AddSomePackage() and app.UseSomePackage()).
3. Remove using statements that reference the package's namespaces.
4. Remove attributes and decorators from content types that reference the package.
5. Check for transitive dependencies. Removing one package may expose missing references (such as Newtonsoft.Json after Search & Navigation removal).
6. Document what was removed so you can re-enable packages when CMS 13-compatible versions are available.
7. Watch for orphaned database artifacts such as scheduled jobs, content types, or database tables that remain after package removal.