Reporting of rendering errors

Last modified by Thomas Mortagne on 2022/01/24 11:59

The rendering framework comes with a set of APIs and extensions points to deal with error reporting.

The main entry point for a code that need to produce a rendering error is the component org.xwiki.rendering.util.ErrorBlockGenerator. It's job is to produce Blocks from the error which can be then be inserted in a content, it's used a lot in contexts where we don't want to stop everything when something fails (a failing macro, etc.).
The component takes the following metadata:

  • inline: indicate if the error is meant to be inserter in an inline content or standalone
  • messageId: the type of rendering error which is expressing (this is used as key for the translating the message and for various extension points)
  • defaultMessage and defaultDescription: the default message and description to print (when no translation is associated to the provided message id). Those follow the SLF4J's Logger syntax
  • arguments: the values to insert in the message and description

  While the SLF4J syntax is supported in translations it's also possible to indicate explicitly the index of the parameter (Missing macro {0}) we want to insert which is very usefull for other languages in which the sentence structure might be very different. It's therefore recommended to be very explicit and use the indexed parameters syntax in the format of the english version located in translation resource to makes easier for translator to understand that parameters can be moved around.

Standard error messages

You can use any identifier you want when you use the error block generator but here are some of the standard identifiers:

  • rendering.async.error.failed: failed to execute asynchronous content
  • uiextension.error.failed : failed to execute UIX (id of the UIX given in the log event)
  • rendering.macro.error.unknown: unknown macro (the id of the macro is the first parameter of the log event)
  • rendering.macro.error.failed: the macro execution failed (the id of the macro is the first parameter of the log event)
  • rendering.macro.error.invalid: the macro is invalid (the id of the macro is the first parameter of the log event)
  • rendering.macro.error.standalone: a standalone macro is used inline (the id of the macro is the first parameter of the log event)
  • rendering.macro.error.invalidParameter: one of the passed parameter of a macro is invalid (the id of the macro is the first parameter of the log event)
  • core.document.error.failedParse: failed to parse the content of a document
  • notification.error.failedRender: error while rendering notification
  • rendering.wikimacro.error.failedResolveContentPlaceholder: failed to resolve macro content placeholder
  • rendering.wikimacro.error.failedResolveParameterPlaceholder: failed to resolve macro parameter placeholder

XWiki extension points

XWiki also provides various ways to customize and extend the behavior of the error generator.

Custom error template

A default displayer is provided for error generation but you can provide your own for a given error message identifier: the path of the template is of the form xwikirenderingerror/<messageId>.vm (for example xwikirenderingerror/rendering.macro.error.unknown.vm). You can also override the default error displayer by providing your own xwikirenderingerror/default.vm.

Augment the standard error displayer

The standard error displayer provides two extension points, both of which are inserted after the description:


Both templates and ui extension are provided with a few metadata related to the error as script bindings the entry point being the variable renderingerror:

  • messageId: the message identifier
  • message: the message as a translated LogEvent
  • description: the description as a translated LogEvent
  • inline: indicate if the produced error is meant to be inline or standalone
  • rootCause: the root cause Throwable in case there is a Throwable associated with the error
  • stackTrace: the stack trace of the Throwable associated with the error
  • Powered by XWiki 15.10.8-node1. Hosted and managed by XWiki SAS

Get Connected