Shelley Bassett



Debugging a customised permalink

June 4, 2018

Sometimes WordPress's pretty permalinks don't work as expected. These are some common issues with using a customised permalink, and how to get your sites urls pointed at the correct place again

Pretty permalinks are a really common sight across the web. They tell you exactly what page you’re on, and also contain useful pieces of information about the site’s hierarchy. WordPress makes it really easy to set up this style of permalink in the Settings -> Permalink options in the admin area. But what happens when a customised permalink suddenly points to a 404 error? It’s okay, the posts aren’t gone, just a little lost.

Think you’ve done it all correctly, but things are still a little wrong? Maybe you’ve added a word or created a custom taxonomy. I’ve found some interesting bugs during my theme development. And some have been easier to solve than others. The WordPress codex unfortunately isn’t much help here. Debugging is often site/ or theme specific and plugins can also have a serious impact. But here are some things you can try to get your links pointing to the desired locations.

Flush the Permalinks

The first mistake is often the most common, and the one that almost every blog and forum lists; flush the permalink settings. It’s the number one for a good reason too. If you’ve made changes anywhere but forgotten to reload the settings, nine times out of ten you’re going to have a bad time. Even if you’ve only made a small adjustment in the functions.php  file, go back to Settings -> Permalinks and hit save. It’s pretty much a catch-all when it comes to customised permalink issues.

Nothing on the blog page

So all your posts are showing on , but there’s nothing at ? This isn’t actually a permalink or url problem, rather, you probably don’t have that set as a page. If your theme allows it, you’ll need a static front page, with a separate page for the feed.

Pages setup

These settings are found in the admin area in Settings ->Reading. The posts page should be set to the word that you’re adding in the url. If it doesn’t exist, add a new page using that word as a slug.

This solutions also applies to custom post types linked to custom taxonomies. If you’re aiming to have your products at  and the product categories at  you’re going to need to create a “products” page, then use the .htaccess files to redirect  there. It’s a simple solution, but can make a website infinitely more functional.

Custom taxonomy slugs are not showing

So you have a hierarchical taxonomy, but the slugs aren’t showing in the correct order, or even at all? Fixing this customised permalink issue requires a bit of fiddly code, but luckily there’s a very nice plugin that will do the job. It even allows for not including a taxonomy in the url, which is great if you have multiple taxonomies that you need presented in different ways.

settings for WP Better Permalinks

My settings for WP Better Permalinks

WP Better Permalinks is a really nifty plugin. Once activated, it’s settings are in Settings -> WP Better Permalinks and are pretty self explanatory. They show the post type, then allow you to select a taxonomy to be displayed. Clean and simple.

Category or post pages have a 404 error

This problem was a bit tricker and took a lot of searching on Google to solve. The solution ended up being a custom rewrite to force the website to use the structure I was after. Just add the following code into your functions.php  of the theme or a custom plug in if you have one, flush the permalinks, and all should be good again.

function permalinkWithCategoryBaseFix() {
    global $wp_query;
    // Only check on 404's
    if ( true === $wp_query->is_404) {
        $currentURI = !empty($_SERVER['REQUEST_URI']) ? trim($_SERVER['REQUEST_URI'], '/') : '';
        if ($currentURI) {
            $categoryBaseName = trim(get_option('category_base'), '/.'); // Remove / and . from base
            if ($categoryBaseName) {
                // Perform fixes for category_base matching start of permalink custom structure
                if ( substr($currentURI, 0, strlen($categoryBaseName)) == $categoryBaseName ) {
                    // Find the proper category
                    $childCategoryObject = get_category_by_slug($wp_query->query_vars['name']);
                    // Make sure we have a category
                    if (is_object($childCategoryObject)) {
                        $paged = ($wp_query->query_vars['paged']) ? $wp_query->query_vars['paged']: 1;
                                              'cat' => $childCategoryObject->term_id,
                                              'paged'=> $paged
                        // Set our accepted header
                        status_header( 200 ); // Prevents 404 status
add_action('template_redirect', 'permalinkWithCategoryBaseFix');