4WebHelp: Creating Custom Error Messages in Apache

In order to have a complete understanding of what a .htaccess file is, I suggest that you also read our Control File Defaults tutorial and our Password Protection tutorial.


The .htaccess file is a file found in Apache servers that allows you to manipulate the behaviour of the server. A very common use is to create custom error messages for server errors. Examples of such errors are "404 Not Found" (say when you click on a broken link), and the "500 Internal Server Error" (a script failed). Most hosts allow you to have your own .htaccess file, and so now we will look at only one of the things we can do with a custom .htaccess.

Some quick notes before we start: under Windows, you cannot save a file with the name of ".htaccess". An easy trick is to create a file called htaccess.txt and edit that. Uploading of the file (regardless of its name) must be done in TEXT/ASCII mode (not BINARY). Finally, under Unix, any file that starts with a '.' is invisible, so when you upload your file, you may not see it. If you uploaded a file called htaccess.txt, just rename it to .htaccess using your FTP client.

Custom Error Messages

What you can do with .htaccess is tell the server to display a special page to the user in case of an error. This page should, ideally, tell the user that something is wrong, down-play the fact that someone messed up (probably you as the webmaster!), and also provide a set of links to the major sections of the site, so the user can at least look for what is missing. Another nice use is to include a search form on the 404 page. You can also tell the server to run a CGI script, instead of simply displaying a static page. If you do this, you can tell the script to log the error for you, or the script can send you an email about the error.

So how do we implement this? Since the .htaccess file is a simple text file, you simply add a line of text to the file, one for each error you want to trap. The general format is:

ErrorDocument 3DigitErrorCode /path/to/your/error/file/or/script

The 3-Digits error codes are as follows:
Error 400 Bad Request
Error 401 Authorization Required
Error 403 Forbidden
Error 404 Missing
Error 500 Server Configuration Error

Thus the following line tells the server to run the error404.cgi script if the server cannot find the requested page.

ErrorDocument 404 /cgi-bin/error404.cgi

This way, you can trap as many errors as you want.

Below is an example of a .htaccess file, just copy and paste into your file, but change the paths:

ErrorDocument 404 /path/to/your/error/file/or/script
ErrorDocument 500 /path/to/your/error/file/or/script
ErrorDocument 403 /path/to/your/error/file/or/script

A very important point to note is that the paths should be the relative paths. This means that the paths would be what you would type on the machine to get to the files, not what you would type in the address box in a browser.

Full path would be http://www.yoursite.com/path/to/error/page
Absolute path would be /home/yoursite.com/path/to/error/page
Relative path would be /path/to/error/page

To summarise the steps, they are as follows:

  1. Create a text file, and add to it a line for each error.
  2. Upload the file to the server, and rename it .htaccess.
  3. Upload the files/script that the .htaccess file calls in each error.
  4. TEST! By typing a weird URL in the address box - you should get the 404 custom error.

Now you are done!

As a final note, a good script to use for this task is the one at BigNoseBird. It is called Birdtrap.

Any troubles/comments please post at the Forums.

This tutorial is adapted from the article that first appeared at http://www.ekstreme.com.

© 4WebHelp and eKstreme

Latest comments on this tutorial
Name: JoEmail joquim dot ttechnologies at gmail dot com
Just configured 404 error page on our site http://www.ttechnologies.in after reading this. I guess too many people ignore the opportunity presented by the 404 page.
Name: KateEmail none
Great points, this is out of the box thinking.
Name: anonymousEmail none
ErrorDocument is useless the server will still show the original message example:
you are trying to access
and you have set ErrorDocument 404 /404.html
you  will see your edited 404 but the http returns 403

you can check it here:
Name: Johnf686Email johnf805 at gmail dot com
Good writeup, I am normal visitor of one's site, maintain up the excellent operate, and It's going to be a regular visitor for a long time. dgeeefdbfecg
Name: JetendarEmail none
Implement the 404 Page Custom Error Message in apache

To edit the 404 page, open up or create the site's .htaccess file. You can create it in a text editor and upload it to your site via the FTP server. Keep in mind that the name of the file has to be simply .htaccess.

Add the following line to the file, replacing new404.html with the correct new error page name:

ErrorDocument 404 /new404.html

Name: audience response technologyEmail cpsclicker at gmail dot com
I think you did an awesome job explaining it. Sure beats having to research it on my own. Thanks
Name: audience response technologyEmail cpsclicker at gmail dot com
Can you please write more blog entries on this subject, its a request, because after reading your blog I am highly interested in learning more.
Name: plebsEmail umbbberto at virgilio dot it
my .htaccess:

ErrorDocument 500 /500.php
ErrorDocument 404 /404.php
ErrorDocument 403 /403.php
ErrorDocument 401 /401.php
ErrorDocument 400 /400.php

it's ok for error 404/401/403...doesn't work for error 400/500...i get the server's answer

any tips?
Name: PowecomARS RentalEmail cpsclicker at gmail dot com
Such a wonderful post. Thanks for the share. It was very interesting and informative.
Name: Powercom ARSEmail arsrentalservices at gmail dot com

Excellent post, went ahead and bookmarked your site. I can’t wait to read more from you.
Name: electronic voting systemsEmail cpsclicker at gmail dot com
Great publish ! I want to learn if you update your blog, can anyone help me subscribe for your weblog?.The idea aided me a good deal. I was little bit aware of that but your post p
rovided apparent thought
Name: indonesiadalamtulisanEmail hanypertiwi at gmail dot com
thanks for article tutorial this great article
Name: shumifan50Email none
Using .htaccess to override the error page(s) is against the pache recommendations as it incurs quite a significant performance hit - many (not just one) files are checked for, and it is loaded for each page. It is highly recommended to use the main configuration files instead with a ErrorDocument directive.
Having said that, I have made ErrorDocument work for normal html page, but I have yet to make it work for cgi scripts.
Name: DanielDkEmail daniel-2630 at live dot dk
Thanks for the post

I seems to have some trouble get it to work, due to understanding issues since im pretty noobish i could really use further help (:

Here is the case:

In the root folder for my site, var/www i have created the .htaccess file, i think im soo wrong to the content, it ONLY contains this line:

ErrorDocument 404 /404-error-page.html

The 404-error-page.html is in the root folder with the .htaccess file also.

Thank you so much
Name: shalinEmail none
Great points, this is out of the box thinking!
Name: FahadEmail none
Thanks worked for me and helped me a lot and some really helpful comments as well..
Name: KevinEmail none
If the .htaccess files don't work, have a look in Apache's configuration file. There is a line that tells Apache to ignore .htaccess files.
Name: white tigerEmail none
it doesn't work Sad
Name: pavan v bEmail mca_pavan82 at yahoo dot com
cau tell me.. while downloading apache2.0 version in to the computer, it is  showing in notepad. why it s happening like this? tell me the solution.
Name: AmitEmail webmaster at creativ-eras dot com
Hi there!!

It's really very useful tutorial for me. It helped me with lot of information. Which i was searching. Thanks you saved a lot of time.
Name: UnapturpopupeEmail mikt9 at ua dot fm
hey.. thank you man
Name: VIP-Branchenbuch.deEmail none
Thanks and sorry for Twice posts


Name: ChrisEmail chris at thinklear dot net
How can we add to the error page some informations about the page that bringed the user there?

I mean - taking somehow the link from which the user was taken to the 404 error page...

I tried with $_SERVER['HTTP_REFERER'] and didn't worked...

Name: AskApacheEmail webmaster at askapache dot com
Nice, this is one of the articles that led me to write about all 57 possible ErrorDocuments available for Apache.  Check it out!  

Name: jintana haskeyEmail mjs_haskey at blueyonder dot com
I can not watch my thai tv on line because erorrw on web site
Name: VkZoomEmail none
The path listed in the .htaccess file is relative to the root of the website, not relative to the .htaccess file.
Name: sourabh deshmukhEmail sdeshmukh1983 at gmail dot com
hi i am working on php and mysql with apache pt. on windows now i want to create a local server so that web page could be open on that local path.
Name: rajkumarEmail rajkumar at infobase dot in
Hi All,

Plz. tell me the process of creating error document in html. I have used .htaccess but it is not secure. I am facing 404 and 403 error on my site.

We can create html error page in which we specify if 404 error encounter then go to this page and 403 error then go to that page, but i donot know that procedure plz. help me  its urgent.

Name: BourneEmail rebourne1211 at gmail dot com
is there a way to get the 404 error page to get the address of the page the user tried to access?

(i have a script that emails me when they get the 404, i want it to nclude the page they tried accessing, so i can see where the problem is.)

Name: Victor BorgesEmail victorlborges at msn dot com
Name: EverettEmail none
I tried this and the error traffic does get sent to my custom page, but the http header now returns a 200 status code. How to I force it to return a 404?
Name: theGeoffMeisterEmail none
PHP Scripts do work! Make sure you pass the information using the GET method, for example:

   ErrorDocument 404 /customerror/error.php?errornumber=404

That would go in your httpd.conf file.

PS - Make sure that all of your links inside are not local. (Include the entire URL for images, CSS, ...)
Name: 404FriendEmail none
Make sure it's a .HTML file...a dynamic page will cause IE to show its own 404 no matter what size it is., I'm assuming this has to do with template matching.  If you trace the network activity, your custom 404.php is being returned...IE just isn't displaying.
-go figure.

Name: JAXEmail none
Make sure your custom Error page is big enough or the damn IE will not diplay it.
Just add some "invisible" text in the html to fill it up.
Name: keypadEmail david at fairlypriced dot co dot uk
Put the .htaccess file in the folder you want to have the custom error pages for.

I have different folders for many different websites I design and each has it's own .htaccess file.

The link in the .htaccess to your error pages is best made by stating the full URL e.g. http://www.yourwebsite.com/foldername/404.html

This is the easiest and least likely to have errors.

The only problem I havent figured out how to overcome is to make it work with links to PHP files.
Name: BrianEmail none
Brad, Seriously did you read any of the posts here?
Name: DavidEmail azndavid6491 at gmail dot com
I put the files on and when I go to sonare.silentcross.net/la or sonare.silentcross.net/la.html it works but if I were to go to sonare.silentcross.net/la.php then the original internet explorer 404 error page shows up. how can this be solved?
Name: MooEmail moo at foo dot com
There is no such thing as htdocs. Or atleast not that I can find.
Name: yaroslavEmail yarlat at mail dot ru
I'm sending the HTML form by POST method to the url '/mypage.php'.
When I use
ErrorDocument 401 /error.php
I lost the POST form data.
Is there any way of getting the POST form data in /error.php?
Name: darrenEmail none
if a website i bring up says 403 forbidden is there anyway to get past that into the website..?
Name: Jakyl401Email none
You can very easily create a file named .htaccess in windows. Open up Notepad do a "save as" enter the name of the file which is ".htaccess" then Save as type: All Files. There you go thats all it takes to create a file in Windows. Razz
Name: JoeEmail ttech5593 at gmail dot com
Hi, I got the 404 and othe error msgs working but is there a way to have the page load and not change the address in the address box? Thanks
Name: prabhuEmail none
hi i need to display an error message saying "FORBIDDEN ERROR -403" using apache. plz help me with this
Name: Robert GreenEmail none
With server - generated error messages, it displays the path of the file that you are trying to access.  If I create a custom error message (like  404) , how do you display the file path?
Name: JoshEmail none
worked awsome nice info
Name: alanEmail phone at yoda dot com
If I put my .htaccess file in the area where the main index.html for the web site is located, then all subsequent links off that page get the bad.html document I created!
Where do I place the .htaccess file so that ONLY www.xnxnxn.com/bad-page-requested gets the hook?
Please reply to phone@yoda.com
Name: SCKSEmail none
Diese Seite ist Offline!!
Technische Probleme!!
Name: BrendanEmail Brendantheman2000 at hotmail dot com
The message letter for letter is "HTTP 403(Forbidden) if that helps you at all.
in regards
Name: BrendanEmail Brendantheman2000 at hotmail dot com
As to my last message, this is kind of urgent, for i do my work through hotmail.
Name: BrendanEmail Brendantheman2000 at hotmail dot com
My room mate has made it so i cannot access hotmail on my computer by making it so that every time i try to access it it comes up with a 403(forbiden) message, is there any way that i can dissable this, or locate the file that tells it to display this and deleate it?
thankyou Brendan
Name: pablo gonzalezEmail pa1_gode2 at hotmail dot com
hola tengo un error en mi pc por favor si me pueden ayudar
se presenta cuando entro en el administrador de visitante
el error dice lo siguiente:
MONITIR:Error[5]creating named fire
y seguido en otra ventana sale lo siguiente:
C Raid_boolApp::InitInstance:
Reg Createkey ex()failed.
acceso denegado
Name: acajajaEmail acajaja at verizon dot net
Putting the Error command in the Apache httpd.conf file worked for me. No need for an .htaccess file unless you want to set for specific dir's. Mac OSX 10.2.8 Apache 1.3
ErrorDocument 400 /your_page.html
Name: hardeshEmail hardesh at gmail dot com
You don't have permission to access /cgi-bin/myfiles/mylogin.cgi on this server.

Additionally, a 403 Forbidden error was encountered while trying to use an ErrorDocument to handle the request.

please help
Name: jim oEmail none
my second url/domain is pointed to the .com. i.e. net will take you to .com. At some point in time .net was cached as links to child pages, the 404 comes from an attempt to reach a child page. I took the .com/ off to get away from microsoft's almost default redirect cookie, moved to an Apache, and developed the 404. How can I allow the .net to take visitors where they wish to go../tv_services.html ect ect?
Name: SteveEmail none
1 thing to remember: Internet Explorer versions 5 and greater have their own 404 error messages built in. It will ignore custom error messagesif they aren't big enough. If you want IE to display your 404 messages, then you have to make it 512 bytes or larger. If you're looking for a way to beef up your page, just add lots of commented out jibberish in the source. Actually, this exact message should do. Just use this format for html comments:

comments here
Name: Hans Pauli DjurhuusEmail hansdjurhuus at simnet dot is
Error 1706SYMPTOMS
When you start your Windows 2000-based computer, you may receive the following error message:
System Process - Unable to Load Device Driver

\SystemRoot\System32\DRIVERS\ipsec.sys device driver could not be loaded.
Error Status was 0xc0000034.
Name: GerryEmail none
My .htaccess file is ErrorDocument 404 /404.html
and is placed in root, along with my webpages.
The 404.html is there also, resarted and same Not Found error is still there, I tried copying the .htaccess line in httpd.conf ,  and still the same.

Apache2 on xp pro and php.

Is there something else I need to configure in the httpd.conf file or elsewhere?

The main reason is that the default 404, 500, etc...shows my apache vs and info.

Name: David McKinkEmail none
Customisable error design pages in

Name: shorty114Email none
You can also add the same lines to your Apache httpd.conf file, to take effect to whole site. I prefer it this way.
Name: WillEmail none
Took me a while to figure this one out so I hope I can save someone some time.

The path listed in the .htaccess file is relative to the root of the website, not relative to the .htaccess file. Thus, if I place the .htaccess file in

and I want to put the 404 page in

and my main index.html file is in

the rules

ErrorDocument 404 404.html

and the rule

ErrorDocument 404 /404.html
will not work since they are both looking for
The rule

ErrorDocument 404 somepath/public_html/test/404.html
will not work since it is looking for

The proper form is

ErrorDocument 404 /test/404.html

of course, this is true no matter where you put the .htaccess file.
Name: willjoEmail none
i have entered this
ErrorDocument 404 /404.shtml

and it wont work?

404 is in the same dir as .htaccess

plz help?
Name: PennerEmail dpenner1 at nc dot rr dot com
usually default is /var/www/html
Name: Shawn lookerEmail hyloth at yahoo dot com
More specifically, the .htaccess file goes in whatever directory you want to change access to.  For example, I have a /usr/local/apache/htdocs directory that has no .htaccess file ,because I want everyone to be able to get there.  I also have a /usr/local/apache/htdocs/test/ directory that does have an htaccess file, because thats where I do my development.
Name: DanielEmail use contact form
brad ingram: The .htaccess file goes in the directory to which you wish to apply a certain settings - usually the root of your site. If your files are in apache/htdocs, then that's where you put the file.

Add a new comment

Page URL: http://www.4webhelp.net/tutorials/misc/errors.php
Back to the "pretty" page!

© 2017, 4WebHelp Team.