.htaccess Generator for WordPress

Options & ErrorDocument Guide

JA

Options Directive

Apache directive that controls which features Apache provides to a directory, enabling or disabling them. By writing in .htaccess , you can control behavior on a per-directory basis.

Syntax

Options [+|-]option-name [[+|-]option-name] ...

When prefixing with + or - , you can add or remove options from the current configuration. Without these symbols, the specified options completely replace the current configuration.

Major Options List

Option Meaning Common Use
Indexes Displays directory listing when no index file exists Use -Indexes to hide listing and prevent direct file viewing
FollowSymLinks Permits following symbolic links Required for WordPress mod_rewrite. Usually enabled
SymLinksIfOwnerMatch Follows symbolic links only if owner matches More secure than FollowSymLinks but slower
MultiViews Auto-selects the best file when accessed without extension Content negotiation (auto language/format switching)
ExecCGI Permits execution of CGI scripts Enable only in directories using CGI
All Enables all options except MultiViews Often used as server default
None Disables all options Used for highly restricted directories

Inheritance and + / - Notation

Options are inherited from parent to child directories. Without + or - , the inheritance is reset and the settings are completely overwritten. 

# Bad example: resets parent settings to only Indexes, losing FollowSymLinks
# This breaks mod_rewrite by removing necessary options
Options Indexes

# Good example: keeps current settings while disabling only Indexes
Options -Indexes

Important: Writing Options Indexes without symbols will reset all options to only what you specify. In contrast, using Options -Indexes with + or - applies relative changes to the current settings. Understand this distinction before using.

Using with WordPress

WordPress requires the mod_rewrite module, which depends on FollowSymLinks (or SymLinksIfOwnerMatch ) being enabled. 

# Typical WordPress .htaccess directive
Options -Indexes +FollowSymLinks

Most shared hosting providers have FollowSymLinks enabled by default, but explicit specification prevents environment-dependent issues.

Important: Some shared hosting environments prohibit changing Options from .htaccess . If you receive a 500 error (Internal Server Error) after adding Options directives, your host may not allow it. In such cases, comment out or remove the Options lines. If errors occur immediately after adding settings, temporarily disable the Options lines to test.

Disabling Directory Listing

When accessing a directory without index.html or index.php , the server displays a file listing by default. Use -Indexes to prevent this. 

<IfModule mod_autoindex.c>
    Options -Indexes
</IfModule>

Exposing directory listings risks revealing site structure and enables attacker enumeration. Always disable in production environments.

ErrorDocument Directive

Customize the response returned when HTTP errors occur. Replace default bland error pages with custom error pages or redirect to another URL.

Syntax

ErrorDocument status-code response

The response can be one of three types:

Type Example Behavior
Local path /error/404.html Internal transfer of server file (URL unchanged)
External URL https://example.com/404 Redirect to external URL with 302 status
Text "Not Found" Return specified text as-is (quotes required)

Local paths should be specified as absolute paths from root (starting with / ). Relative paths can be used but are not recommended because their resolution varies depending on error location.

Common Error Codes and Their Use

Code Meaning Customization Purpose
400 Bad Request Error page for malformed requests (control chars in URL, etc.)
401 Unauthorized Custom message for failed Basic authentication
403 Forbidden Access denied page (displayed after deny from all , etc.)
404 Not Found Page not found. Most frequently customized
500 Internal Server Error Server error from PHP failures or configuration mistakes
503 Service Unavailable Page during maintenance or temporary service downtime

Custom Error Page Configuration Example

# Example setting three commonly used custom error pages
ErrorDocument 403 /error/403.html
ErrorDocument 404 /error/404.html
ErrorDocument 500 /error/500.html

Error page files are normal HTML files. When referencing CSS or images, use absolute paths from root (since error pages can be accessed from any URL, relative paths may not resolve correctly).

Maintenance Page Implementation

To put the entire site in maintenance mode, use RewriteRule to return a 503 status and ErrorDocument 503 to specify the maintenance page. 

<IfModule mod_rewrite.c>
    RewriteEngine On
    # Don't redirect the maintenance page itself
    RewriteCond %{REQUEST_URI} !/maintenance.html$
    # Exclude images, CSS, JS
    RewriteCond %{REQUEST_URI} !\.(css|js|png|jpg|gif|ico|svg)$ [NC]
    RewriteRule ^(.*)$ - [R=503,L]
</IfModule>

# Return 503 status (tells search engines we're temporarily down)
ErrorDocument 503 /maintenance.html

During maintenance, returning 503 informs search engine crawlers that the site is temporarily unavailable. Using redirect ( R=302 ) results in a final 200 OK response, which harms SEO. Instead, use R=503,L to return 503 directly, then specify the page with ErrorDocument . Optionally include a Retry-After header to indicate when crawlers should retry.

Caution for WordPress Environments

In WordPress environments, 404 errors are handled by WordPress itself, so ErrorDocument 404 typically has no effect. WordPress's rewrite rules forward non-existent paths to index.php , where WordPress returns a 404 template. 

# WordPress .htaccess (auto-generated by WordPress)
# RewriteRule ^(.*)$ index.php [L]
# ↑ Since all requests go to index.php, Apache's ErrorDocument 404 isn't used

To customize WordPress 404 pages, edit the theme's 404.php file.

403 and 500 are processed by Apache itself, so ErrorDocument functions correctly for these codes.

← Back to Generator