I ran into a problem when setting up this blog. It took me hours to fix because I could not find a solution in the search engines. So, I thought I would document the problem here for the next poor guy (or gal!) who might stumble upon it.

The problem

I developed the theme for this blog locally using Local. This was a great experience, and I was able to tweak things until I got it just right.

I set this site up quickly on Akamai’s Linode, using their WordPress marketplace app. I chose the LEMP stack because this closely matched the default Locals environment. Once the installation finished, I uploaded the theme and began testing it. I noticed fairly quickly that the custom 404 page I designed (the page where you end up if you mistype a link) was not displayed by my browser.

The solution

I spent several hours trying to find an answer. I wasn’t very familiar with the NGINX web server and I thought that surely someone else had seen this problem.

I was wrong.

I finally ended up at the WordPress setup instructions at nginx.com, where I noticed that the nginx site configuration file (/etc/ngingx/sites-available/site.conf) slightly differed from those provided by Linode.

Here is what I saw:

server {
   ...
   location / {
      try_files $uri $uri/ /index.php?$args =404;
   }
...
}

I changed this to:

server {
   ...
   location / {
      try_files $uri $uri/ /index.php?$args;
   }
...
}

Removing the ‘=404‘ bit at the end of the try_files directive fixed the problem and my WordPress site now works as expected.