I recently came across an extremely weird issue on a WordPress website. One of my clients contacted me saying that they cannot set a static page as the website’s front page on a pretty new WordPress instance. The email with the subject ‘WordPress “static page” missing’ had one attachment:
I took the website over, cloned it on my local server and checked it. Sure enough, I saw the exact same issue so I started debugging.
In case you are not very familiar with WordPress and you don’t understand exactly what is wrong, I will add another screenshot of an image that shows the expected content on the Reading Settings page:
The “Debugging Process”
Over the years I had to debug countless WordPress websites. By doing so, I started developing a “debugging process” that is made of a few steps.
Step 1: Make sure everything is up to date
The first thing I usually do is make sure the WordPress instance, plugins and themes are all up to date.
In this case, it was almost perfect with just 4 items needing updates including the WordPress update. I ran the updates to the latest versions on all plugins and the WordPress instance, checked again and noticed that the issue was still there.
Step 2: Blame it on a plugin
Most of the times, malfunctioning plugins or themes are the troublemakers on WordPress websites.
Having said that, I moved on to checking if there is a plugin causing this problem.
There are two different approaches:
1. Disabling the plugins manually.
Navigate to the WordPress Admin Panel -> Plugins and then start disabling plugins until you see the issue fixed.
You can also disable all the plugins at once by checking the “Select All” box at the top of the table and then selecting the “Deactivate” option in the “Bulk Actions” select box.
2. Renaming the plugins folder
In case you are used to working with the files of your website, there is a nice solution for quickly disabling all the plugins.
Navigating in the wp-content folder of your website and simply renaming the plugins folder to something else will do the trick. I usually just rename it to plugins1
Keep in mind that I am still on the local instance of the website and I am not doing it on the server or on a public website. In case you want to do debugging on the “live” version of a website, make sure you backup the files and the database before doing it!
After renaming the folder and going back to the plugins page of your website admin panel you will see something like this:
Even though this looks like a pretty quick solution, you have to understand that by doing this the plugins don’t run their normal uninstall procedures. So all the data of the plugins will remain untouched in the database. This happens because WordPress can no longer find the uninstall actions in each plugin so it just considers they don’t exist.
Enough of that. Let’s get back to our “debugging process”. For this specific step, I decided to go with the 2nd solution because I specifically did not want the data to be affected in any way.
After doing that, I checked the Reading Settings page again to see if it got back to normal. Unfortunately, this was not it either. So I just reactivated all the plugins again and moved on to the next step.
Step 3: Blame it on the theme
As you know, WordPress themes can also hold code that affects both the front end and the back end of the WordPress website. This means we definitely have to take the theme into consideration when debugging an admin panel issue.
This website is using one of the best light WordPress themes I ever found online. It is called GeneratePress and it works with the Gutenberg editor. It also supports Beaver Builder and Elementor in case you like those better.
When doing this we have to start by checking if the website has an active child theme. You can do that by navigating to Appearance -> Themes and clicking the active theme box. This will open a popup with the current theme’s details. In case you see a section with the text: This is a child theme of GeneratePress. you will know for sure that the website runs on the child theme of GeneratePress.
For deactivating the child theme you can just activate the parent theme instead and then check the main problem. If the static page section is still not showing up, the next step is to activate one of the standard WordPress themes.
In my case, the website had the Twenty Twenty theme installed so I just activated that one. Afterwards I checked the Reading Settings page again.
The result is negative again. So, back to square one. Reactivate the GeneratePress child theme and move on to the next step.
4. Getting hands dirty
At this moment we know that none of the easy solutions worked. That means we need to go and have a look at what happens behind the scenes in the code.
But, where do we start?
One generally applicable rule is that whenever a URL has the .php file extension, you should navigate to that file. That is most probably the entry point of the script that is rendering the page.
Going back at the Reading Settings page in the admin panel we can see that the URL of the page is https://domain.com/wp-admin/options-reading.php. As mentioned above, whenever we have a .php file, we start from there. So we navigate to the wp-admin folder in our WordPress install folder and search for the options-reading.php file.
In this file we now search for one of the texts we see on the page. For example: Blog pages show at most. According to the normal display of this page, this should be right under our Static Page section. So we look above it and try to find the previous section. Here is the code we are looking for ( lines 70 - 147 on WP 5.4.2 ):
At this point I already knew what the issue was, but I will try to break it down for you.
If you have a look at the first line in this code gist, you can see that there is a condition that needs to be met: if ( ! get_pages() ). However, if we go further down to see what the code actually does, on line 9 in the gist there is an else : followed by some HTML including some of the text we are looking for: Your Homepage Displays. This is some text that should be displayed on our Reading Settings page but it is not.
Let’s try to understand that condition and see why our text does not show up.
First of all let’s have a look at what the get_pages() method does. For that we can check the official WordPress documentation. Here we can see that the method can take a parameter to allow the caller to change some of the options. Also, it will return an array of pages or false in case there are no pages to match the options.
Going back to the gist above, we can see that the get_pages() method has no parameters, meaning that it will run on the default options. Moreover, given the fact that the text we are looking for ( line 16 in the gist ) is under the else branch of the if statement and that our text is not showing means that get_pages() is returning false so the if clause can not reach the else branch.
After all this, all we have to do is look through the get_pages() method options and see which one(s) could cause the return to be false. Going through them, nothing really stands out as possible culprits except for the last 2 options:
- ‘post_type’ – (string) The post type to query. Default ‘page’.
- ‘post_status’ – (string|array) A comma-separated list or array of post statuses to include. Default ‘publish’.
These two options put together working only with their default values can be translated to:
give me all posts with the 'post_type' = 'page' and 'post_status' = 'publish'.
There it is. We now have all we need to draw a conclusion and fix the problem.
Drawing the conclusion
Considering the fact that the get_pages() method returns all pages that are published and, in our case, it returns false means one thing:
We don’t have any pages with the status ‘publish’!
If we go into our Pages section in the admin panel to check our theory we see this:
There you go. Mystery solved!
Sure enough, after I published one of the pages, the result was the one you would expect and the one you can see here:
Wrapping Up
Debugging can be cumbersome. However, it can also be fun and it can definitely make the subject of a story like this.
Thank you for reading until the end. I hope you enjoyed the story and that you also managed to learn some basic stuff about debugging in WordPress.
Make sure you check my most popular plugin: Search Analytics
I find this article really nice and interesting because it has all that I am looking for. You have to keep on with this good work, by writing more interesting post. Thanks for sharing this article.