Skip to main content

How to configure the Forgiving mode

⚠️This document describes a feature available since v4.0.1+⚠️

Introduction#

Due to various reasons a Sitecore item may contain a rendering on the layout details that throws an error during rendering. The standard Sitecore rendering process would ignore such a rendering and show an error in the logs. In contrast to that, the Uniform's Page Service the renders each rendering individually works a bit differently. This means that a rendering that throws an error will make the Page Service fail. Since this may break the operation of Uniform APIs, such capabilities as Static Site Generation and Content Sync will be effected. The Forgiving Mode is one of the options to address this issue.

Here are some examples of the build-time errors that you may see when running Static Site Generation, which may indicate that the Forgiving Mode is relevant for your solution:

  • Error occurred prerendering page "/". Read more: [https://err.sh/next.js/prerender-error:](https://err.sh/next.js/prerender-error:) Error: Cannot find component ABC
  • Can't find even a single {guid} rendering at /sitecore/content/Home/about at home/about page
  • Cannot find implementation of 'ABC' React component. Check if it is added to the component map.

When the Forgiving Mode is enabled, the renderings that fail to render during Page Service execution, will not cause the failure of the Page Service, and therefore will not break the Static Site Generation or Content Sync operations.

Please review the Additional Considerations section, as there are some side effects for you to consider before enabling this feature. The alternative solution to enabling the Forgiving Mode is to use the Experimental MVC Support feature, which resolves this particular issue differently.

How to use#

Before you enable it - additional considerations#

  • The important side effect of enabling this feature may not be desirable, depending on your use case. The Forgiving Mode effectively hides any renderings that fail during rendering. While this takes care of the rendering that fail "by design", this will also hide any renderings that failed due to an unexpected condition during Static Site Generation or Content Sync, which bends the rules of Jamstack quite bit, as there is a chance that some renderings being skipped that should have otherwise been rendered. We recommend removing any failing rendering that is not supposed to be rendered, therefore fixing the problem of failing Page Service calls without Forgiving Mode.
  • If your Sitecore page rendering is broken during normal rendering process due to a bad code within any rendering or on the layout itself, the Forgiving Mode won't help. The page rendering error has to be fixed before the Page Service can be functional on a given page.

Configuration#

Simply add a config include patch with the following Uniform.MvcSupport.SkipBrokenRenderings setting, which needs to be set to true as it defaults to false:

<configuration xmlns:set="<http://www.sitecore.net/xmlconfig/set/>">  <sitecore>    <settings>      <setting name="Uniform.MvcSupport.SkipBrokenRenderings" set:value="true" />    </settings>  </sitecore></configuration>

Notice that set: suffix was used in front of a the value attribute. It is a best practice, making the order in which the config files are loaded by Sitecore not important.