• Home
• FAQs
• Forums
• Links
• Online Tools
• phpBB
• Scripts
• Tutorials:
• Apache
• CSS
• Databases
• Graphics
• Hosting
• HTML & XHTML
• Miscellaneous
• Perl
• PHP

• About us
• Contact us
• Credits
• Link to us

Write a tutorial for us
Bookmark this tutorial

Print this tutorial
Comment on this tutorial

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.

Introduction

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.

Examples:
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
Tejas
Just configured the 404 error page on our site - https://digital.trivoli.in/ using this tutorial.
Joquim
Very sound tips, thanks! https://raunakgroup.com
Big J
Just configured 404 error page on our site - https://www.whistlingwoods.net using this tutorial.
RUGHA RAM
Caller id changer problems error coad 401unauthorizd
Joquim
Very practical tips, truly an eye-opener. http://www.hafoos.com
Jo
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.
Kate
Great points, this is out of the box thinking. http://www.citizenumbrella.com
anonymous
ErrorDocument is useless the server will still show the original message example: you are trying to access www.example.com/.htaccess and you have set ErrorDocument 404 /404.html you  will see your edited 404 but the http returns 403 you can check it here: https://www.hurl.it/
Johnf686
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
Jetendar
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 http://www.vardhamaninfotech.com/?page_id=49
audience response technology
I think you did an awesome job explaining it. Sure beats having to research it on my own. Thanks
audience response technology
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.
plebs
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? thanks
PowecomARS Rental
Such a wonderful post. Thanks for the share. It was very interesting and informative.
Powercom ARS
Excellent post, went ahead and bookmarked your site. I can’t wait to read more from you.
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
indonesiadalamtulisan
thanks for article tutorial this great article
shumifan50
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.
DanielDk
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 -D-
shalin
Great points, this is out of the box thinking! http://www.holytraffic.com
Fahad
Thanks worked for me and helped me a lot and some really helpful comments as well..
Kevin
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
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.
Amit
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.
Unapturpopupe
hey.. thank you man
VIP-Branchenbuch.de
Thanks and sorry for Twice posts VIP-Branchenbuch.de
Chris
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... Chris http://www.ThinKlear.net/
AskApache
Nice, this is one of the articles that led me to write about all 57 possible ErrorDocuments available for Apache.  Check it out!   http://www.askapache.com/htaccess/apache-status-code-headers-errordocument.html
jintana haskey
I can not watch my thai tv on line because erorrw on web site
VkZoom
The path listed in the .htaccess file is relative to the root of the website, not relative to the .htaccess file. http://www.negative-seo.net
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.
rajkumar
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. Rajkumar
Bourne
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.) ty
Victor Borges
I NEED A PAGE FOR HOMEWORK BUT ERROR 403 SHOWS UP. WHAT SHOULS I DO?
Everett
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?
theGeoffMeister
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, ...)
404Friend
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.
JAX
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.
keypad
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.
Brian
Brad, Seriously did you read any of the posts here?
David
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?
Moo
There is no such thing as htdocs. Or atleast not that I can find.
yaroslav
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?
darren
if a website i bring up says 403 forbidden is there anyway to get past that into the website..?
Jakyl401
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.
Joe
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
prabhu
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?
Josh
worked awsome nice info
alan
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 thanks
SCKS
Diese Seite ist Offline!! Technische Probleme!!
Brendan
The message letter for letter is "HTTP 403(Forbidden) if that helps you at all. in regards Brendan
Brendan
As to my last message, this is kind of urgent, for i do my work through hotmail.
Brendan
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: EN UNA VENTANA SALE: MONITIR:Error[5]creating named fire y seguido en otra ventana sale lo siguiente: C Raid_boolApp::InitInstance: Reg Createkey ex()failed. acceso denegado
acajaja
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
hardesh
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
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?
Steve
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. CAUSE
Gerry
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. confused!
David McKink
Customisable error design pages in http://perso.wanadoo.es/gonzisp FREE-NOT REGISTER
shorty114
You can also add the same lines to your Apache httpd.conf file, to take effect to whole site. I prefer it this way.
Will
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 /somepath/public_html/test/.htaccess and I want to put the 404 page in /somepath/public_html/test/404.html and my main index.html file is in /somepath/public_html/index.html the rules ErrorDocument 404 404.html and the rule ErrorDocument 404 /404.html will not work since they are both looking for http://website.com/404.html The rule ErrorDocument 404 somepath/public_html/test/404.html will not work since it is looking for http://website.com/somepath/public_html/test/404.html The proper form is ErrorDocument 404 /test/404.html of course, this is true no matter where you put the .htaccess file.
willjo
i have entered this ErrorDocument 404 /404.shtml and it wont work? 404 is in the same dir as .htaccess plz help?
Penner
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