If an uncaught exception is thrown when updating a ZUML page (aka., when an event listener is executing), it is handled by the ZK Update Engine. By default, it simply asks the browser to show up an alert dialog to tell the user.

You can customize the error handling by specifying the error page in WEB-INF/zk.xml as follows. Refer to Appendix B in the Developer's Reference.

<!-- zk.xml -->
<error-page>
    <exception-type>java.lang.Throwable</exception-type>    
    <location>/WEB-INF/sys/error.zul</location>    
</error-page>

Then, when an error occurs in an event listener, the ZK Update Engine creates a dialog by use of the error page you specified, /error/error.zul.

Like error handling in loading a ZUML page, you can specify multiple <error-page> elements. Each of them is associated with a different exception type (the value of <exception-type> element). When an error occurs, ZK will search the error pages one-by-one until the exception type matches.

In addition, ZK passes a set of request attributes to the error page to describe what happens. These attribute are as follows.

For example, you can specify the following content as the error page.

<window title="Error ${requestScope['javax.servlet.error.status_code']}"
width="400px" border="normal" mode="modal">
    <vbox>    
KillerApp encounters a fatal error, ${requestScope['javax.servlet.error.message']}. The error is recorded and we will look at it and fix it soon.
        <hbox style="margin-left:auto; margin-right:auto">        
            <button label="Continue" onClick="spaceOwner.detach()"/>            
            <button label="Reload" onClick="Executions.sendRedirect(null)"/>            
        </hbox>        
    </vbox>    
    <zscript>    
    org.zkoss.util.logging.Log.lookup("Fatal").log(    
        requestScope.get("javax.servlet.error.exception"));        
    </zscript>    
</window>

Tip: The error page is created at the same desktop that causes the error, so you can retrieve the relevant information from it.

Tip: Since 2.3.1, ZK won't make the root window as modal automatically, since some applications may prefer not to use modal windows at all. If you prefer to use modal windows, you can specify the modal mode as shown in the previous example.

<!-- zk.xml -->
<error-page>
    <device-type>mil</device-type>    
    <exception-type>java.lang.Throwable</exception-type>    
    <location>/WEB-INF/sys/error.zul</location>    
</error-page>