For almost two hours I was pulling whatever hair is left out of my head because I was registering a custom post type, and its posts, archives and categories would generate 404 errors using the %category%/ %postname% permalink structure. I knew that my post type was fine so there was just something that kept messing up my work. In my case it was another plugin that was causing the errors but I figured I should put a semi-compete troubleshooting list together so you can fix your Custom Post Type permalink errors.
First thing first, let’s register a Custom Post Type called book and give it a pretty slug “book”.
This means that when you add a post under this type, your permalinks would be:
and the archive for this post type would be:
What happens here is that WordPress tries to rewrite your slug to “book” and this is where the problems begin.
Things to check:
- Before you do anything else, first go to setting/permalinks and re-save the permalink structure. This will hard flush the rewrite rules inside your htacess and most of the time will fix your problem. If you’ve re-saved your permalink structure and the problem still exists go the next step.
In your functions.php right after:
register_post_type( ‘book’, $args ); // your slug and arguments will be different obviously
Save, upload the file, and test again. If the permalink starts working, it means that your post type is registered correctly and something else is messing it up. Go ahead and remove the line you just added as although it seems that it fixed the problem, it’s just a band aid and not a good one either. What this function does is that it constantly flushes the rewrite rule with every request so you definitely don’t want it in there. Now that we know the post type registration was OK, Proceed to the next step.
- Make sure you don’t have a page, category, tag, post, tag base, or category base with the same slug. This means if you have a page called Book with a slug “book”, WordPress will go crazy and rightfully so. The fastest way to find out is to dump your database and open it with a text editor like Notepad++ and do a search for book. If you see a duplicate somewhere, rename either your custom post type slug or fix the other page. If this doesn’t fix the problem, proceed to the next step.
- This is where the real troubleshooting begins. If you have a custom theme, switch to one of the default themes that ship with WordPress like the Twenty Eleven or Twenty Twelve. Re-save the permalinks structure again and test. If this doesn’t fix it, proceed to the next step.
- Disable all the plugins and resave the permalinks again. This will definitely fix your problem so test and see. Now that we know that your theme is fine, your custom post type is fine, and permalinks have been flushed, there is only one possibility. It’s one of your plugins that’s calling the flush function and is doing wrong.
Start activating your plugins one at a time, resaving the permalinks after each activation, and test your custom post type. This will pin point your problem source and then you either have the option to ditch the faulty plugin, report it to its developer, or try to fix it yourself.
Hope this comes handy the next time you’re pulling your hair out of your skull. If you have questions or comments, leave them below.