Kentico Xperience Page Builder: Troubleshooting tips

Introduction

One of Kentico Xperience's most powerful features 💪 is the built-in Page Builder. When the Page Builder is activated, content editors and marketers are given a tool 🧰 to enrich the digital platform with building blocks 📦 in the form of Kentico Widgets.

When the Page Builder is running, features such as A / B testing 🧪 and personalization become a breeze to use. It's a must have in any Kentico Xperience project.

Because their are a variety of ways to setup your solution architecture in ASP.NET Core MVC, e.g. pick and choose core components like the preferred dependency injection 💉 framework, the Page Builder may not work immediately. In this post I will provide troubleshooting tips 💡 to check and get the Page Builder working in your Kentico Xperience project.

✔️ Checklist for troubleshooting

• Check if the Page tab is visible/accessible for the content item #duh
• Check if you can create a new content item with Page Builder enabled
• Check if the Preview mode works and shows the content item
  • Check if the Page type URL Pattern is set correctly
  • Check if CMSHashStringSalt value matches in CMS and MVC
  • Check and re-sign Macro signatures
  • Check length of maxUrlLength within httpRuntime
• Check for Javascript errors using the browser console
  • Check the Content-Security-Policy for blocked resources
  • Check for Cross-Origin Resource Sharing (CORS) errors
  • Check for potential conflicts with jQuery
• Check if the CMS and MVC run on the same hotfix version
• Check if the combination of CMS and MVC URLs match correctly
• Check for relevant errors in the Event Log
• Check the fixed bugs regarding Page Builder on Kentico DevNet
  • Check the CMSPreviewLinkExpiration setting (since 12.0.47)
• Check and review Page Builder development areas
  • Check if Page Builder is enabled in Application_Start
  • Check if Page Builder is enabled before registered routes
  • Check for Page Builder namespace in Views\web.config
  • Check for Page Builder initialization in custom routes
  • Check if Editable areas and Sections are setup correctly
  • Check if Page Builder scripts and styles are present
• Check if your custom URL module is blocking Kentico system URLs
  • Check for paths /cmsctx and /Kentico.*

💥 Potential error messages

Error message #1:
The page builder feature is not enabled. You need to call the 'UsePageBuilder()' method of the Kentico.Web.Mvc.ApplicationBuilder instance at the start of your application's life cycle.

Error message #2:
An error occurred while attempting to retrieve page templates. Contact your system administrator and check that the page builder feature is registered correctly in the MVC project.

Error message #3:
This preview URL has already expired. Please contact a responsible person to provide you with a valid preview URL.

Error message #4:
Error: Request failed with status code 404 in builder.js or vendors.js

Error message #5:
Refused to frame 'https://www.yourdomain.com' because an ancestor violates the following Content Security Policy directive: "frame-ancestors https://admin.yourdomain.com https://www.yourdomain.com".

Error message #6:
Access to XMLHttpRequest at '...' from origin '...' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Error message #7:
Message: The '...' default section identifier doesn't represent registered section.

💼 Specific fix when using Simple Injector

There was one error message which was very specific to our setup:

Error message #8:
A single instance of controller 'Kentico.PageBuilder.Web.Mvc.Internal.KenticoComponentDefaultController' cannot be used to handle multiple requests.

In our Solution Architecture we used Simple Injector as our preferred Dependency Injection framework. Initially the Page Builder seemed to work up until we introduced Page Templates with multiple editable areas.

This can be solved by changing the Lifestyle of the internal called KenticoComponentDefaultController to Transient:

container.Register(() => new KenticoComponentDefaultController(), Lifestyle.Transient);

This change alone is not enough, because the controller implements IDisposable. This results in the following error message:

Error message #9:
The configuration is invalid. The following diagnostic warnings were reported: -[Disposable Transient Component] KenticoComponentDefaultController is registered as transient, but implements IDisposable.

The issue can be fixed as follows:

container.RegisterDisposableTransient<KenticoComponentDefaultController, KenticoComponentDefaultController>();

For more information see the Simple Injector documentation.

Summary

There are a lot of areas that interact with the Page Builder and therefore there can be many reasons why the Page Builder might not work. Hopefully with this post I have outlined an approach to quickly find the root cause. Feel free to share your Xperiences 😉 in the comments.