How to troubleshoot .htaccess problems

The .htaccess file can be very useful, however it can also be time consuming and frustrating trying to track down issues within it. The goal of this guide is to provide you with resources to help identify and troubleshoot common .htaccess problems, as well as give a few tips that you can use to help should you run into problems related to this file.

Note: To avoid having to troubleshoot problems with your .htaccess file by yourself, we recommend using a BoldGrid Official Partner web host for your WordPress hosting needs. They are certified WordPress and BoldGrid experts, and can make issues like this go away in a flash. Back to the regularly scheduled article!

The .htaccess file

The .htaccess file is a configuration file for web servers that run the Apache Web Server Software. When an .htaccess file, or Hypertext Access File, is detected within a web site’s document root, it is then loaded, and any rules in the file are executed. The .htaccess file is extremely useful for making configuration changes to the Apache service that only apply to the directory (and its subdirectories) in which they are added. You can perform redirects, change a sites header, and create SEO Friendly URL’s that exclude the file extension, and add a trailing slash (/) making the link appear like a folder, rather than a file.

The most common error that you will see with .htaccess file problems is a 500, or Internal Server Error, as seen below.

Common Reasons .htaccess is not working

Possible Typos

If you are replacing, or recreating the file, then you must be sure the filename is correct and that it begins with a period “.” If the period is not at the beginning, Apache will ignore the file – this will occur if it is misspelled as well.

Rule Location

Some rules will affect others. If you have added a rule, and it is not working you may want to try and move it above any directives you have already, or even to the top of the file to see if that works. The reason being when .htaccess it read by Apache, it does so from top to bottom, and some rules may be conflicting with what you are attempting to add.

Conflicting .htaccess files

An .htaccess file’s rules apply to the directory that it is in, as well as any sub-directories that are within that directory. Because of this, an .htaccess file in a higher level directory can affect your site files as well. An easy way to narrow down whether this is a cause would be to rename the .htaccess file, which will effectively disable it.

Incorrect Syntax

The most common issues with .htaccess files are syntax related. Syntax errors in .htaccess will cause 500 errors in Apache. Make sure you check the file to ensure you are using the correct syntax for the directive in question.

You can reference Apaches .htaccess documentation for further information.

How to troubleshoot .htaccess issues

Use an .htaccess validator

You can use tools such as http://www.htaccesscheck.com/ to validate and check your syntax. This is very useful in identifying any errors that may cause problems.

Check Apache Error Logs

If you make changes and your site breaks, you can check the Apache error log, which is normally located at /var/log/apache2/error_log

For example, if I added a . to the bottom of an .htaccess file, and when the site loads, this error can be found within the Apache error log:
Invalid command ‘.’, perhaps misspelled or defined by a module not included in the server configuration

Debugging with Apache Configuration

If you have access to the httpd.conf file, you can add your .htaccess file inside of a directory tag, and it will allow any errors to be logged, which will point out the issues you may be having quicker.

Here is a sample of the configuration you can use:

# BEGIN WordPress
 
 RewriteEngine On
 RewriteBase /
 RewriteRule ^index\.php$ - [L]
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule . /index.php [L]
 
# END WordPress
.

The Apache error log would then point directly to the line that has the error, helping troubleshooting by pointing to the exact location of the issue. In this case, it would be a stray “.” at the end of the file which could easily be overlooked.

Enable Mod_Rewrite Logs

If you’re using Apache’s mod_rewrite module, you can enable the rewrite log to give you details about any issues you may have. To accomplish this, you will need access to the Apache configuration file.

You can find out more about enabling this log in the Apache documentation

404 Errors / Permalink Settings

One of the most common errors when dealing with WordPress Permalink problems is a Server Level 404 Error. This is fixed by either adding back the permalink rewrites in .htaccess, or navigating to Settings > Permalinks and clicking save.

Not Generated During Inspirations

If your .htaccess file is not automatically generated during Inspirations, then there is likely an issue with your file permissions, or your web server’s Apache configuration.

Default WordPress .htaccess

There are multiple configurations for permalinks, as you have the option to change or customize them to suit your needs. Here are the default .htaccess files for WordPress single and multisite uses:

WordPress Single Site:

# BEGIN WordPress

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

# END WordPress

WordPress Multisite

Subfolder Example

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]

# add a trailing slash to /wp-admin
RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]

RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
RewriteRule ^([_0-9a-zA-Z-]+/)?(wp-(content|admin|includes).*) $2 [L]
RewriteRule ^([_0-9a-zA-Z-]+/)?(.*\.php)$ $2 [L]
RewriteRule . index.php [L]

SubDomain Example

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]

# add a trailing slash to /wp-admin
RewriteRule ^wp-admin$ wp-admin/ [R=301,L]

RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
RewriteRule ^(wp-(content|admin|includes).*) $1 [L]
RewriteRule ^(.*\.php)$ $1 [L]
RewriteRule . index.php [L]

.htaccess rules for NGINX

Since NGINX does not use an .htaccess file, you would have to apply your rewrites directly to the configuration. To accomplish this, you can use a converter tool, such as https://winginx.com/en/htaccess which will give you the correct syntax to use for NGINX. You would then apply this to your NGINX configuration file.

Congratulations! With the troubleshooting techniques provided, you now have more information as well as some common steps to help solve common .htaccess problems. Looking for more? We have tons of other WordPress tutorials and articles for you to check out!