In this article, I will describe an issue that I had when the permalinks to my Leaflet custom post type temporarily broke, sending an unfortunate number of visitors to a 404 page until I resolved the issue.
WordPress admins who are not developers (I assume none of this will be news to developers) can consider this story a a quick-fix guide for creating and managing custom post types.
Our Leaflet Custom Post Type
On April 3, 2022, I introduced a new type of post at The New Leaf Journal called Leaflets. Leaflets are intended to be short-form posts without all the flourishes of our full-length content. I added Leaflets to The New Leaf Journal as a new custom post-type by writing a specific plugin for the task instead of using one of the many freely available custom post type plugins in the WordPress repositories. While this was successful for creating Leaflets (albeit not with a minor URL snafu), I found myself unable to create a new custom post type that did not return a 404 error. Rather than explore the issue, I contented myself with having created the Leaflet custom post type and continued producing content. Only when the issue struck the poor Leaflets did i decide to investigate.
The Leaflet custom post type proved to be a boon to The New Leaf Journal in the last week. First, a short Leaflet that I wrote about an unusual search engine appearing in my logs unexpectedly made the first page of Hacker News. Then, a second Leaflet that I wrote about a man uploading 2,000,000 videos to YouTube also made page 1 of Hacker News and achieved even greater traffic despite the fact that the link to my article was swapped out for the YouTube channel in question not too long after it was posted.
Not bad for two tiny posts that I likely spent a combined 10 minutes writing and formatting.
An Ill-Fated Update to WordPress 6.0
On the evening of May 24, 2022, as the surge of traffic to the YouTube Leaflet began to wane, I saw that I had an update to WordPress version 6.0 available. While things can go sideways in updates, I have never had an issue with one. I dutifully created a backup of The New Leaf Journal and then updated.
Immediately after updating, everything appeared to be normal. However, when I tried to edit an older post, I found that I could not access WordPress’s default block editor. Strange. It turned out that I could access the editor for my Leaflet posts (which are not edited with the block editor), so the issue was only afflicting the Gutenberg editor.
I temporarily downgraded to the previous version of WordPress, 5.9.3, and discovered that everything worked with no issue. Hoping against hope the first update had gone a bit sideways for unknown reasons, I tried re-upgrading to WordPress 6.0. Once again, I could not access the block editor for any of my non-Leaflet posts.
We would have to resort to annoying measures.
Deactivating and Reactivating Plugins
The first thing to check when a WordPress update goes sideways is whether a plugin is causing the issue. While I am very careful and selective about the plugins that I choose to employ on The New Leaf Journal, opting always for lightweight plugins that are well-maintained and tailored to specific tasks, I do have a decent number of plugins. To begin my quest to figure out what was wrong with WordPress 6.0, I deactivated every plugin en masse. Recall that the Leaflet Custom Post Type is powered by a plugin that I wrote. It was deactivated along with the rest.
Upon deactivating every plugin on The New Leaf Journal, I found that I could access the block editor. That was good. I would not have been happy if it was a theme issue.
I slowly reactivated the plugins one by one and tested the editor. None of the early plugins were triggering the issue. I confirmed that my Leaflet plugin was not the culprit around the middle of my search and I reactivated it.
It turned out that the issue was a single setting (out of many) in the very useful Unbloater plugin that I primarily use to regulate the system heartbeat. After I went through its settings again, I confirmed that The New Leaf Journal was fully functional with the full slate of plugins, I rebuilt our cache and prepared to end my New Leaf Journal work for the evening.
Ominous Signs Overlooked
After confirming that The New Leaf Journal was again working, I did not click on any links to Leaflet articles our our archive (had I done so, I would have seen a problem). However, there was a sign of a Leaflet-related problem that I overlooked before I signed off for the evening (or morning) a bit after midnight. Allow me to begin with a preface.
We use a privacy-friendly local analytics plugin called Koko Analytics (see my review). Koko Analytics relatively reliably tells me how many page hits The New Leaf Journal receives, how many hits individual articles receive, and where our visitors come from if the referring link sends a referrer header (I set it up such that it is less reliable in detecting repeat visitors). I noticed on the very early morning of May 25 that we had a large number of what I will describe here as “unaccounted for pageviews.” By this I mean we had a bit more than double the number of page views to views assigned to specific articles. Koko Analytics does not list views for the homepage, our archives, or our search pages, so in theory it was possible that visitors were sifting through our archives. However, I will note that the vast majority of our total pageviews can usually be attributed to articles, pages, and Leaflets.
No matter. It was late. I was tired and I had my day job in the morning. I let the issue be.
Discovering a Custom Post Type Permalink Problem
I checked in on The New Leaf Journal in the morning to share a couple of posts externally, see how we were doing, and make sure that everything was in working order. I noticed that the number of unaccounted-for pageviews had increased, still a bit more than half of the total. For one reason or another, I tried to open a Leaflet micropost. Instead of being taken to the Leaflet, I was taken to a 404 page. Another Leaflet revealed the same result. Sure enough, the entire Leaflet archive also returned a 404 page.
In light of the fact that the second of the Hacker News Leaflets was still commanding a good amount of traffic and had recently generated a large number of backlinks to The New Leaf Journal, I considered the state of affairs to be highly sub-optimal. Just how many readers hoping for heart-throbbing content in the previous 11 or 12 hours had instead found a 404 page? Brutal. Imagine their disappointment.
The Solution: Flush Rewrite Rules
The issue that I was facing with the Leaflets was precisely the same issue that I had run into when I tried to make an additional Custom Post Type. Something was amiss. I knew that I needed a solution quickly, so I ran a couple of searches and found a Stack Exchange thread from 4 years ago that seemed promising. In response to a WordPress admin who also had broken Custom Post Type permalinks, one kind responder explained:
“You need to flush rewrite rules on plugin activation for your custom post type to begin working.”
That sounded very promising. Sure enough, my Leaflet plugin had been working before I had to temporarily deactivate it, and it appeared to stop working after deactivating it. While I do have full root access to our WordPress install, I do not actually know how to flush the rewrite rules manually. Because the situation was a bit urgent, I decided to look for a plugin created by people who actually know what they are doing to do the job for me.
After a quick search, I settled on the Rewrite Rules Inspector plugin. Although it had not been updated in more than one year, one of the developers of the plugin is Automattic – the company behind WordPress. The tests that I looked at revealed no code warnings and it did not add anything heavy to the site. I installed the plugin and went into the Rewrite Rules Inspector menu.
The menu highlighted issues with our rewrite rules and suggested flushing all of the rules. To make the task easy, the plugin has a convenient “Flush Rules” button. You only live once, I thought, so I flushed the rules.
Immediately after flushing the rewrite rules, our Leaflet posts were accessible again. While I was disappointed that a decent number of potential new visitors had found a 404 page when they tried to visit the Leaflet, I am glad that the issue did not occur when we were receiving a flood of new visitors and also that I was able to catch and resolve it quickly (albeit not as quickly as I would have liked).
All’s Well That Ends Well
To be sure, it would have been better for me to have been more curious about my failure to get other custom plugins for custom post types working and then resolved the issues before it affected visitors. But the bright side of the unfortunate 12-hour Leaflet incident is that I now know how to create new custom post types. To commemorate the occasion, I created a new “Resource” custom post type that I will use for Resource pages instead of our regular “Page” post type (that is a bit miscast for resources). After flushing our rewrite rules, the new Resource archive page is accessible. Now that I know how to make my custom post type plugins work, I may add a few other interesting sections to The New Leaf Journal over the coming months.