Howto: Language negotiated error documents


Well-Known Member
Apr 25, 2008
sanctum sanctorum
I have been looking for a permanent solution to the error document mess on my server. The default CPanel installation comes with the following statement in httpd.conf
Include "/usr/local/apache/conf/includes/errordocument.conf"
which contains paths to various error documents that are supposed to be in /usr/local/apache/htdocs directory. Unfortunately, except most common five, they are not there.

In addition, Apache default installation comes with an error directory (/usr/local/apache/error on my server) which contains multi language error documents.

I spent some time today setting my server to serve those multi language error documents in cases where it was not overridden by a specific host using .htaccess. It took me a while to figure out exactly what to do so I will put it here in case it is any use to someone else, and in the hope that if there is something I overlooked someone will warn me.
Apache 2+ (because of SetOutputFilter, may be adjusted for Apache 1)
mod_include (comes as default, you can also enclose entire thing in an <IfModule>)

First remove the
Include "/usr/local/apache/conf/includes/errordocument.conf"
from httpd.conf, and re-distill with
/usr/local/cpanel/bin/apache_conf_distiller --update
Alternatively, remove everything from errordocument.conf and save it as a blank document.

Next, add the following to httpd.conf using Main >> Service Configuration >> Apache Configuration >> Include editor > Pre Main Include
# Apache default installation comes with a directory /error
# where multi-language error documents are kept.

# Define the error document to be served for each error
# to be those that come with Apache.
# We put this in server context, so it applies to all
# hosts defined on this server, unless it is overridden
# by a specific host.
ErrorDocument 400 /error/HTTP_BAD_REQUEST.html.var
ErrorDocument 401 /error/HTTP_UNAUTHORIZED.html.var
ErrorDocument 403 /error/HTTP_FORBIDDEN.html.var
ErrorDocument 404 /error/HTTP_NOT_FOUND.html.var
ErrorDocument 405 /error/HTTP_METHOD_NOT_ALLOWED.html.var
ErrorDocument 408 /error/HTTP_REQUEST_TIME_OUT.html.var
ErrorDocument 410 /error/HTTP_GONE.html.var
ErrorDocument 411 /error/HTTP_LENGTH_REQUIRED.html.var
ErrorDocument 412 /error/HTTP_PRECONDITION_FAILED.html.var 
ErrorDocument 413 /error/HTTP_REQUEST_ENTITY_TOO_LARGE.html.var
ErrorDocument 414 /error/HTTP_REQUEST_URI_TOO_LARGE.html.var
ErrorDocument 415 /error/HTTP_UNSUPPORTED_MEDIA_TYPE.html.var
ErrorDocument 500 /error/HTTP_INTERNAL_SERVER_ERROR.html.var
ErrorDocument 501 /error/HTTP_NOT_IMPLEMENTED.html.var
ErrorDocument 502 /error/HTTP_BAD_GATEWAY.html.var
ErrorDocument 503 /error/HTTP_SERVICE_UNAVAILABLE.html.var
ErrorDocument 506 /error/HTTP_VARIANT_ALSO_VARIES.html.var

# When an error occurs, the host will be looking for a directory
# called error, give it to them.
Alias /error /usr/local/apache/error 

<Directory "/usr/local/apache/error">	
	# Allow acces to this direcory by everyone
	Order allow,deny
	Allow from all
	# We need this for Language negotiation
	AddHandler type-map .var
	# We need this as files in error directory
	# and the directories below are SSI so we set
	# *everything* in this process as SSI.
	Options Includes
	SetOutputFilter INCLUDES	 
Finally, delete *.shtml in /usr/local/apache/htdocs (optional)

Now you can make any customization to top.html and bottom.html in /usr/local/apache/error/include directory.
The results are like this (minus any customisation I made in /usr/local/apache/error/include)

English 404
Korean 404

Above makes following assumptions:
  • Options Includes was restricted by a higher directory context. If not you can omit that line.
  • Access to /usr/local/apache/error was restricted by a higher directory context. If not, you can omit the lines "Order allow,deny" and "Allow from all".
  • No host will have a directory called error immediately below their document root. Actually, I renamed the /usr/local/apache/error to /usr/local/apache/402FFD9DBBD079 as it is unlikely that anyone will have such a directory. Obviously, one must replace all occurrences of error in above description with 402FFD9DBBD079.
  • You make a backup of any original file before making changes so if something goes wrong... :)
  • Like
Reactions: Infopro