I recently had to setup some rewrite rules for a website using Apache’s mod_rewrite.  Most of our sites are on shared servers so I can just upload that .htaccess file and be done, but every now and then I’m on a new dedicated server where some things just aren’t setup correctly.  I’m not really a server person since I mostly deal with php and javascript, so when I have to delve into server configuration I always feel uneasy.  I started out by googling “troubleshoot mod_rewrite” and found a whole lot of snippets, but nothing really helped me solve my particular issue.  Admittedly, my issue was unique but I think the first few steps may just help you out.
  1. Check your AllowOverride Directive
  2. Is mod_rewrite being loaded?
  3. Check your log file
  4. Can you break it yet?
  5. Try a simple redirect rule first
  6. Check for overwritten settings

Check your AllowOverride Directive

This is the most common problem with your rewrite rules not working.  This basically tells Apache what directives your .htaccess is allowed to overwrite.  You will probably want to change this to “All” and be done with it.

  1. Open up your httpd.conf in your editor of choice.
    vim /etc/httpd/conf/httd.conf
  2. Find the “AllowOverride” directive in the directory settings for your site. For vim type “/Directory” to search for directory and then just keep pressing “n” to find the right one.
  3. Change the “AllowOverride” directory to “All”.
  4. Save your changes and restart apache.

Is mod_rewrite being loaded?

  1. Open up your httpd.conf again
  2. Search for the long list of “LoadModule” directives.
  3. On of them should look like “LoadModule rewrite_module modules/mod_rewrite.so”
  4. If that line isn’t there, make sure that file exists and then add the LoadModule line above.
  5. If the file doesn’t exists, you probably need to install mod_rewrite.  That is out of my expertise, but you should be able to google more information about it.

Check your log file

I place this next since it gives me a good indication of whether mod_rewrite is actually installed and loaded.  Mod_rewrite comes with some directives that can be placed in the server config or vhosts section of your apache configuration files to enable logging of your rewrites.

  1. Place the following somewhere in your config file.  This tells apache to use rewriting and log everything about it.  EVERYTHING.
    RewriteEngine On
    RewriteLog /var/log/httpd/apache_rewrite
    RewriteLogLevel 9
  2. Save your config file and restart apache.
  3. Hit a page on the website you are testing to engage the log.
  4. Check the log file path you put into the config for information.
  5. If the log file is empty, you may need to check permissions, but more than likely your mod_rewrite is not installed correctly.
  6. If the log isn’t empty, make sure to put the log level back to 0 (zero) and restart apache since it will slow down your server.

Can you break it yet?

I include this since it’s a always a strong debugging tool for code.  Basically, if you can break it then you have control over it enough to fix it.

  1. In your .htaccess file, put in something that will break it (misspell an directive) and save it.
  2. If your server gives you a big fat error when you hit your site, then remove what you put in and rejoice that you can actually get back to not having to mess with apache.

Try a simple redirect rule first

The next step we always do is to put in the simplest rules possible.  If those work, then we need to work on the individual rules we have laid out for everything else.

  1. Redirect everything to an external site.  Redirecting everything is pretty simple and if it goes to something else, you know it is working.
    RewriteEngine On
    RewriteRule (.*) http://www.google.com/
  2. If the rule above worked, remove it and then start checking your spelling and regular expressions for your other rules

Check for overwritten settings

Unfortunately, I can’t provide much direction here since most server setups are different than mine. All I can say is go through your entire httpd.conf file with a fine-toothed comb. Pay particular attention if there are any “Include” statements.

This is what happened to me.  On this particular server, at some point we will probably have multiple sites running so it was setup with that in mind.  When we do this, we don’t really like having to search the giant httpd.conf file for everything so we include other configuration files, one of those is specifically for vhosts declarations.  Normally, the httpd.conf contains directory settings for /var/www/html and vhosts.conf contains settings for each sites directory below that so /var/www/html/site1.  This time, the httpd.conf and vhosts.conf contained directory settings for the same directory /var/www/html/site1.  Vhosts.conf had AllowOverride All; however it was included before the directory setting in the httpd.conf which had AllowOverride None.  So, I had the most basic problem, but because my directory settings were declared in 2 spots it was a pain to find.

I hope this helps someone out there debug their mod_rewrite install.


  1. Something important to be added to the “overwritten settings” section:

    Check for .htaccess files in subdirectories that may be overwriting your rules. If you specify rewrite rules in /.htaccess relating to /files, but have failed to edit or remove the contents of /files/.htaccess, then your rules may be ignored.

    Thanks for the guide Yancey – very useful.

  2. Thanks for this tutorial Yancey. You had me at “AllowOverride All”. Just upgraded my Mac to El Capitan, and suddenly my versioned stylesheets & JS were not working.

    Glanced at httpd.conf, and saw that I had AllowOverride None. A quick change, a `sudo apachectl restart`, and I’m back in business.

    At least, back to figuring out what else the upgrade messed up…

  3. Hi Yancey, very good article.
    It sounds obvious, but I would suggest you to add a comment about not leaving … behind. Some rewrites must be specifically added inside it.

  4. the other comment omitted the virtual host tag

Leave a Comment