Fixing the “Permalink Not Working on Localhost” Error in WordPress

Dominic

Founder and CEO, Emohelp.com

WordPress Tutorial -

When working on a WordPress site locally, you might encounter an issue where custom permalinks don’t work, and you’re stuck with the default permalink option. If you change the permalink structure in Settings > Permalinks, your site might display an error like this:

Not Found
The requested URL was not found on this server.

This issue usually happens because your local server isn’t configured to handle custom URLs. Don’t worry! This guide will walk you through fixing it.

Why Does This Happen?

WordPress relies on the Apache module mod_rewrite and a correctly configured .htaccess file to handle custom permalinks. If either of these is missing or misconfigured, WordPress cannot rewrite URLs properly, leading to errors.

Step-by-Step Guide to Fix the Error

1. Enable mod_rewrite in Apache

The mod_rewrite module is responsible for rewriting URLs. If it’s not enabled, your custom permalinks won’t work.

  • For MAMP, XAMPP, or WAMP:
    1. Locate the Apache configuration file:
      • MAMP: [MAMP Directory]/conf/apache/httpd.conf
      • XAMPP: [XAMPP Directory]/apache/conf/httpd.conf
    2. Open the file in a text editor.
    3. Search for this line:apacheCopy code#LoadModule rewrite_module modules/mod_rewrite.so
    4. Remove the # at the beginning to enable the module:apacheCopy codeLoadModule rewrite_module modules/mod_rewrite.so
    5. Save the file and restart Apache.

2. Check or Create the .htaccess File

WordPress uses a file called .htaccess to manage URL rewriting rules. Without this file or if it’s not configured correctly, custom permalinks won’t work.

  • Go to your WordPress installation folder.
  • Ensure there is a file named .htaccess. If it doesn’t exist, create one.
  • Add the following content to .htaccess:
# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress
  • Save the file.

Note: If you’re on Windows, make sure the file is named .htaccess (with the dot) and not htaccess.txt.

3. Update VirtualHost Configuration (Optional)

If you’re using a custom VirtualHost for your local WordPress setup, make sure it allows overrides.

  • Locate your VirtualHost configuration file:
    • MAMP: [MAMP Directory]/conf/apache/extra/httpd-vhosts.conf
    • XAMPP: [XAMPP Directory]/apache/conf/extra/httpd-vhosts.conf
  • Ensure the <Directory> section for your WordPress folder includes this line:apacheCopy code<Directory "/path/to/wordpress"> AllowOverride All </Directory>
  • Save the file and restart Apache.

4. Restart Apache

After making changes to the configuration files, restart Apache to apply the updates:

  • Stop and start the Apache server in your control panel (e.g., MAMP, XAMPP, or WAMP).

5. Update Permalinks in WordPress

Now that the server is configured correctly:

  1. Go to Settings > Permalinks in your WordPress admin dashboard.
  2. Select your desired permalink structure (e.g., Post Name).
  3. Click Save Changes.

Common Pitfalls and Troubleshooting

  • Still Not Working? Check the Apache error log (usually located in the logs/error.log directory of your Apache server) for clues.
  • Missing .htaccess File: Ensure your operating system shows hidden files and double-check the folder.
  • Other Local Servers (Nginx): If you’re using Nginx instead of Apache, the configuration process will be different. You’ll need to update the Nginx configuration file instead.