


Creating Custom Error Messages in Apache by eKstreme

Last updated: 02/05/2012

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
Absolute path would be /home/
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

© 4WebHelp and eKstreme

Latest comments on this tutorial
Just configured the 404 error page on our site - using this tutorial.
Very sound tips, thanks!
Big J
Just configured 404 error page on our site - using this tutorial.
Caller id changer problems error coad 401unauthorizd
Very practical tips, truly an eye-opener.
Just configured 404 error page on our site after reading this. I guess too many people ignore the opportunity presented by the 404 page.
Great points, this is out of the box thinking.
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:
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.


ErrorDocument 404 /new404.html
audience response technology
audience response technology
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?
PowecomARS Rental
Powercom ARS

electronic voting systems
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
thanks for article tutorial this great article
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.
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
Great points, this is out of the box thinking!
Thanks worked for me and helped me a lot and some really helpful comments as well..
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.
white tiger
it doesn't work Sad
pavan v b
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.
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.
hey.. thank you man
Thanks and sorry for Twice posts

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...

Nice, this is one of the articles that led me to write about all 57 possible ErrorDocuments available for Apache.  Check it out!
jintana haskey
I can not watch my thai tv on line because erorrw on web site
sourabh deshmukh
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.
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.

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.)

Victor Borges
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?
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, ...)
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.

Just add some "invisible" text in the html to fill it up.
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.

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.
Brad, Seriously did you read any of the posts here?
I put the files on and when I go to or it works but if I were to go to then the original internet explorer 404 error page shows up. how can this be solved?
There is no such thing as htdocs. Or atleast not that I can find.
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.
if a website i bring up says 403 forbidden is there anyway to get past that into the website..?
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
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
hi i need to display an error message saying "FORBIDDEN ERROR -403" using apache. plz help me with this
Robert Green
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?
worked awsome nice info
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 gets the hook?
Please reply to
Diese Seite ist Offline!!
Technische Probleme!!
The message letter for letter is "HTTP 403(Forbidden) if that helps you at all.
in regards
As to my last message, this is kind of urgent, for i do my work through hotmail.
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
pablo gonzalez
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
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
You don't have permission to access /cgi-bin/myfiles/mylogin.cgi on this server.


please help
jim o
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?
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
Hans Pauli Djurhuus
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.
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.


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

David McKink
Customisable error design pages in

You can also add the same lines to your Apache httpd.conf file, to take effect to whole site. I prefer it this way.

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.
i have entered this
ErrorDocument 404 /404.shtml

and it wont work?

404 is in the same dir as .htaccess

plz help?
usually default is /var/www/html
Shawn looker
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.
Daniel, 4WebHelp Team Member
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
