Customised error views

The default error view

The howtos.customisingerrorpages example simulates a programming error when you click on ‘Submit’.

The config setting reahlsystem.debug = True in controls how an uncaught Exception in your application is handled.

If reahlsystem.debug = True, then a stacktrace is shown.

If reahlsystem.debug = False, your application renders a default error view derived from the root UserInterface (set in web.site_root config in

The default error view is sufficient in most cases.

This example has its web.site_root set to BreakingUIWithBuiltInErrorPage which demonstrates the default behaviour:

class BreakingUIWithBuiltInErrorPage(BreakingUI):

Supplying a completely customised error view

Uncomment web.site_root = ‘BreakingUIWithCustomErrorPage’ in etc/ to see the example customised error view.

BreakingUIWithCustomErrorPage is a different UserInterface which defines a customised error view by calling define_error_view() in its assemble():

class BreakingUIWithCustomErrorPage(BreakingUI):
    def assemble(self):

The Widget used in the call to define_error_view() replaces the entire HTML5Page when the error view is shown. On your Widget, provide a class-side method with the same name and signature as get_widget_bookmark_for_error(). In your get_widget_bookmark_for_error(), return a page-internal Bookmark to an instance of your Widget which is parameterised to display the given error message.

ErrorWidget or ErrorMessageBox() are handy to use for this purpose:

class CustomErrorPage(HTML5Page):
    def __init__(self, view):
        error_widget = self.body.insert_child(0, ErrorWidget(view))
        error_widget.add_child(H(view, 1, text='Oops, something broke'))
        error_widget.add_child(P(view, text=error_widget.error_message))
        error_widget.add_child(A(view, Url(error_widget.error_source_href), description='Click here to try again'))

    def get_widget_bookmark_for_error(cls, error_message, error_source_bookmark):
        return ErrorWidget.get_widget_bookmark_for_error(error_message, error_source_bookmark)