ErrorDocument FAQ and Mustgather¶

The documentation required to diagnose problems with ErrorDocument handling includes

web server and plug-in configuration files
web server and plug-in log files
network trace showing flows between browser and web server when reproducing the error

Table of Contents¶

ErrorDocument FAQ and Mustgather

Check for known issues¶

Error codes set by WebSphere applications¶

The ErrorDocument directive does not apply to HTTP error responses received from WebSphere Application Server by the WebSphere plug-in. It does apply to errors encountered by the WebSphere plug-in, such as failure to connect to an application server.

Internet Explorer problem with Show friendly HTTP error messages enabled¶

If the browser which does not display the desired ErrorDocument text is Internet Explorer, it may be due to the Show friendly HTTP error messages setting in the Advanced Internet Options.

It is usually simple to identify when Internet Explorer is displaying its own message for an HTTP error instead of what the server sent. The bottom left-hand corner of the error page will show "Internet Explorer", as in the following example:

_images/friendly.gif

The Show friendly HTTP error messages setting can be disabled, but that requires client modifications. The usual solution for this is to increase the size of the error document. Try a 64K document. Contact Microsoft support for definitive information on how to avoid having Internet Explorer display friendly messages without updating the client settings.

Problems with `ErrorDocument 413` processing¶

Normally, there are two components in the web server which can detect the post size limit problem:

WebSphere plug-in:

The administrator can specify the PostSizeLimit parameter in plugin-cfg.xml. The plug-in can then detect that the limit has been exceeded, and it will return a 413 HTTP status code to IBM HTTP Server, which in turn will return it to the web client (browser).
IBM HTTP Server:

The administrator can specify the LimitRequestBody directive in httpd.conf, and IBM HTTP Server can then detect that the limit has been exceeded, and it will return a 413 HTTP status code to the web client (browser).

Either of these checks will prevent a WebSphere application from seeing the request when the body size is more than the specified number of bytes.

The HTTP protocol also allows the browser to detect the problem. The optimal way to handle such limits is for the browser to implement the optional Expect: 100-continue handshake with the server so that the browser first tells the server the size of the upload, then the server tells the browser whether or not it is okay based on the size, then the browser either continues with the upload or displays an error to the user.

Popular web browsers such as Internet Explorer do not implement the Expect: 100-continue handshake. Instead, they simply start uploading the data, however large, and continue uploading until done. It is only at the end of the upload that they may see a 413 response from IBM HTTP Server (probably sent long before).

During the time that the web browser is still uploading the request body, IBM HTTP Server may drop the connection (after having already sent an error response). If the browser sees that the connection is dropped during the upload, it often will not see the error message which was sent previously, so the user will not see any error message.

IBM HTTP Server will not read unlimited amounts of request body when it has already been identified as too big. That ties up web server resources for too long and could consititute a Denial of Service. Given that the web server may drop the connection before the entire request body has been read, and that the web browser will not process the error response if it finds out that the connection has been dropped before it finishes uploading, the error message from the web server may or may not be displayed, depending on:

size of upload (smaller uploads increase likelihood of seeing error response)
size of error response (larger error responses increase likelihood of seeing error response)
network bandwidth

A plug-in module could be written for IBM HTTP Server 2.0 and above which will cause the web server to read the entire request body before the error is sent. That usually results in the web browser displaying the desired message. However, this is not recommended for production use since it can tie up web server resources for a long period of time (as long as it takes the client to upload an arbitrary amount of data). It could be used for a denial of service attack.

Local URLs for 413 error documents¶

Local URLs cannot be used for custom 413 error documents; "plain text string" and full URLs (redirects) can be used.

Problems with other HTTP status codes¶

HTTP 400¶

If IBM HTTP Server fails to parse the request, an HTTP status code of 400 is generated and ErrorDocument directives that point to a local URL will be ignored and the default message will be used. Full (absolute) URLs and plain text strings are still processed as normal.

If the request is read and parsed successfully but a 400 is generated later on during the request (e.g. encoded slashes, too many .. in URL), ErrorDocument directives using local URLs (as well as full URLs and plain text strings) are processed as normal.

If the Websphere Plug-in loses its connection to the client while writing the response, a status code of 400 is logged but no error message of any kind can be sent to the client.

HTTP 401¶

If you use an ErrorDocument 401 directive then it must refer to a local document. Otherwise, the client will not receive 401 and therefore it will not prompt for credentials.

Trying variations of the `ErrorDocument` directive to see if that resolves the problem¶

There are several mechanisms for specifying the desired error text. Try each of them to see if the problem is resolved.

ErrorDocument with plain text string¶

ErrorDocument 404 "The file you requested was not found.

This mechanism has the problem that it is inconvenient to specify a document large enough to override the Internet Explorer Show friendly HTTP error messages setting.

ErrorDocument with javascript in plain text string¶

ErrorDocument 404 "<html><body onload=\"top.location.replace('/404.html')\"></body></html>"

(Replace "/404.html" with the desired local URL.)

Some customers have found that this is the easiest way to have the browser display the desired error document.

ErrorDocument with local URL¶

ErrorDocument 404 /404.html