Understanding XPages Error Codes
During this year I’ve done a session looking under the hood of XPages and explaining what actually happens. I firmly believe (and the evaluations and feedback suggests I’m not wrong) that when you understand what’s happening, it builds confidence.
The starter for the session was XPages and error codes – a gentle introduction, but still valid.
Everyone knows XPages is display on the web via the Domino server. But even that is an over-simplification that leads to some confusions for those who don’t appreciate what’s actually happening. There are two key components in play in delivering XPages to the user. The Domino HTTP server and the XSP Command Manager. This is true for XPages on the web and the Notes Client. Both require an HTTP server and the XSP Command Manager.
So why is that important? It’s important because your point of access is the Domino HTTP Server and several checks are made before the XSP Command Manager is even called.
Step 1: Can the HTTP Server resolve the address to an NSF?
The first check is whether everything up the “.nsf” corresponds to a Notes Database. If not, the HTTP server throws an HTTP 404 error. This is displayed using the standard Domino HTTP error page. If you want to offer a pretty response to this error, it’s no good creating an XPage. You need to take the traditional Domino web approach of either adding a $$ReturnGeneralError Form or using the Domino Web Server Configuration database. With XPiNC, this throws the same errors as a standard Notes Client database.
Step 2: Does the use have access to the database?
Again, this is a check by the Domino HTTP server (or Notes Client, in the case of XPiNC). If not, an HTTP authentication page is delivered. Again, for XPiNC, standard Notes Client responses occur.
Step 3: Can the HTTP server find the relevant resource in the database?
Again, we’re still governed by the Domino HTTP server. If the resource cannot be found in the database, again, the HTTP server throws an HTTP 404 error.
Step 4: Does the signer have access to run XPages?
For web, again the Domino HTTP server handles this check, checking against the relevant field in the Server document – “Sign agents or XPages to run on behalf of the invoker” on the Security tab. For XPiNC that check is it made. Instead, a check is made against the Notes Client’s Execution Security List (ECL). If the signer is granted access, the XPage loads, regardless of the server setting.
Step 5: Are there any fatal error preventing the XPage being loaded?
This is the final check done by the HTTP server. What do I mean by fatal errors? I mean dependencies on any Java code that cannot be found, which prevent the XPage being successfully compiled and processed by the XSP Command Manager. Examples of such errors are:
- Java classes for e.g. managed beans that have fallen out of the Build Path for the database
- Extension libraries that are not installed on the relevant server (web) or Notes Client (XPiNC)
- Java code that is prevented from running because of security restrictions in the java.policy file (usually something that uses java.util.logging)
If this occurs, the Notes Log or server console points to the IBM_TECHNICAL_SUPPORT folder. You need to check the relevant error file, which will point to the relevant class that either could not be loaded properly because of security issues or was not available. XPages Log File Reader project on OpenNTF is extremely useful for checking those files.
If everything else is fine…
The XSP Command Manager finally takes over. Any errors from now on are XPages-related and can be handled via a custom error page or enabling “Display XPages Runtime Error Page” in the Application Properties.