The water never truly forgets. Even when redirected, rivers carry traces of what once was — like memory, flowing toward tomorrow.
***
There is nothing more frustrating than clicking a link on your own site only to be met with a cold “404 Not Found” page. It feels like a dead end for your visitors and a headache for you.
In the world of WordPress, a 404 error rarely means your content is gone forever. Usually, it just means your server has lost the “map” it uses to find your posts. This is incredibly common after migrating to a VPS, switching to Docker, or simply tweaking your URL structure. In this guide, we’ll walk through the technical fixes to get your routing back on track and your visitors where they need to go.
The Anatomy of a WordPress 404 Error
Before we dive into the terminal, let’s look at why this happens. On a VPS or Docker setup, the most common culprits are usually technical “handshake” issues:
- Corrupted Permalinks: The internal WordPress “rulebook” for URLs is out of sync with your database.
- Nginx Misconfiguration: Your server doesn’t know how to pass requests to index.php.
- Rewrite Failures: Missing instructions in your .htaccess (Apache) or configuration blocks (Nginx).
- Docker Volume Lag: Your containers aren’t reading the site files correctly after a change.
STEP 1 — The Magic Permalink Reset (Try This First)
In many cases, you don’t need code to fix a 404. You just need to give the database a gentle nudge.
- Go to Settings → Permalinks in your WordPress dashboard.
- Do not change any settings. Just scroll to the bottom and click “Save Changes.”
Why this works: Clicking “Save” forces WordPress to flush and regenerate its rewrite rules. This often instantly fixes “Page Not Found” issues on posts while the homepage works fine.
STEP 2 — Repairing the .htaccess File (Apache Users)
If you are using a standard Apache setup, your .htaccess file might be missing or corrupted. Replace its contents with the default WordPress block to reset the foundation:
BEGIN WordPress
RewriteEngine On
RewriteBase /
RewriteRule ^index.php$ – [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
# END WordPress
STEP 3 — The Nginx and Docker “Try_Files” Fix
Nginx doesn’t use .htaccess files. If you are using Docker or a VPS with Nginx, you must explicitly tell the server to send all requests to WordPress’s index.php.
Check your Nginx site configuration (or Nginx Proxy Manager “Custom Configuration” block):
location / {
try_files $uri $uri/ /index.php?$args;
}
After saving the config, restart your container to apply the changes:
docker restart wpfox_app
STEP 4 — Force a Rewrite Flush via Code
If you can’t access the Admin dashboard at all, you can force WordPress to fix itself by adding this line to your functions.php file temporarily:
flush_rewrite_rules();
Note: Remove this line as soon as the site is fixed. Leaving it there is resource-intensive because it forces WordPress to rebuild the URL map on every single page load.
STEP 5 — Isolate Plugin and Theme Conflicts
Sometimes a security or SEO plugin hijacks your URL structure. Here is the surgical approach to finding the culprit:
- Bulk Deactivate: Turn off all plugins. If the 404 disappears, one of them is causing the break.
- The One-by-One Test: Reactivate them slowly, checking your site after each one until the error returns.
- Theme Check: Briefly switch to a default theme (like Twenty Twenty-Four) to ensure your custom theme isn’t missing a required template file.
STEP 6 — Verify Docker Network Routing
If your homepage works but all subpages give a “404 Not Found” (often an Nginx error page rather than a WordPress one), your reverse proxy likely isn’t passing the URI correctly.
Check your active containers:
docker ps
Ensure that your wp_app container is communicating correctly with your db container. Also, verify that the volume mapping for /var/www/html is identical in both your Nginx configuration and your Docker Compose file.
STEP 7 — Clear Your “Invisible” Cache
Sometimes the 404 is “stuck” in a cache layer even after the technical problem is solved. Clear these three layers to be sure:
- Local: Clear your browser cache or test the site in an Incognito window.
- Server: Clear WP Rocket, LiteSpeed, or any object cache like Redis or Memcached.
- Edge: If you use Cloudflare, use the “Purge Everything” option.
Common Mistakes to Avoid
- Hardcoded Links: Avoid using absolute URLs in your posts; use relative links or internal WordPress linking tools instead.
- Ignoring Case Sensitivity: On Linux servers, “My-Page” and “my-page” are treated as different locations. Ensure your slugs match exactly.
- Migration Mishaps: Always run a “Search and Replace” on your database when changing domains to update file paths and serialized data.
Final Result: A Seamless User Experience
- Zero Broken Links: Your users can navigate your content without friction.
- SEO Integrity: Search engines can crawl and index your pages without running into errors.
- Server Health: Your Nginx/Apache configuration is now optimized for WordPress routing.
Essential WordPress Troubleshooting
- How to fix 502 Bad Gateway in WordPress
- How to fix WordPress White Screen of Death
- How to speed up WordPress on VPS
- How to secure your WordPress website
Your WordPress routing is now fully restored. No more dead ends for your visitors!
Share:
