WordPress 3.1 Broken Tags/Categories culprit found

With plenty of time to spare today, I decided to quickly set up a WAMP server in a Virtual PC environment running Windows XP and tried to see if I could replicate this issue.  After spending a couple of hours trying to find the magic combination of WordPress updates between 2.9.2 (my original version) and version 3.1, the categories always worked fine once I landed on version 3.1.

So I figured that maybe I’m using certain characters on this blog’s categories and descriptions that’s causing the issue.  So I started again with WordPress 2.9.2, created the same categories as this blog, added test articles to them and tried a various combinations of upgrades.  Once again, the categories still worked fine in version 3.1.

At this stage, I started wondering if there was something else in my blog’s database that’s upsetting the upgrade.  With my blog already on version 3.1, I decided to just import the database into WAMP and see what happens if I force the upgrade.  This was simple enough by changing “db_version” to 15344 in phpMyAdmin and running the database upgrade by logging into wp-admin.  To my surprise, the categories and tags started working again.  However, this database upgrade trick did not work on this live blog.

After reverting the database in WAMP to do some more experimenting, I noticed I made a mistake with the site address in phpMyAdmin while preparing the database for WAMP.  I noticed the mistake in Settings, General in wp-admin and corrected the link in the field “Site address (URL)”.   When I was about to try some experimenting with plug-ins, I noticed that the categories were already working despite not forcing the database upgrade this time, so I realised I came upon an alternative to updating the database.  Again, repeating this trick on this live site did not work.

Next, I decided to download this entire blog and run it in WAMP.  This time, neither the database upgrade trick nor the live site address change trick would get the category pages working, so at least I knew it was not a problem with my hosting provider and that the culprit must be a plug-in or the theme.

Finally, I disabled the plug-ins one by one, repeating the site address update trick until the category pages started working again.  I eventually landed on the multi-page toolkit and sure enough, once I enabled this plug-in again, the categories and tags links stopped working.

Replicating the bug:

To confirm the multi-page toolkit plug-in was at fault, I created a fresh WordPress 3.1 installation in WAMP with a new database, set up permalinks (I use “/content/%post_id%/%postname%”), added a test category and a page to the category.  Here is how the category page looked at the front end (click to enlarge.)

I downloaded and installed the multi-page toolkit, version 2.6 at this time of writing.  I installed it by placing its folder directly in the WordPress plugins folder.  I then went into wp-admin to enable it:

Finally, I returned to the home page and opened the category page. Voila – “Not Found”:

In the meantime, there are two ways to overcome this bug (other than disabling Permalinks):

Method 1 – Apply this WordPress Tags/Categories fix by Luke America over at WP Code Snippets.  This is what SSD Freaks here is using.

Method 2 – Disable the Multi-page toolkit.  Then go into Settings, into General and make an alteration to the “Site address (URL)” field, e.g. add a ’1′ to the end of the URL.  Save the changes, remove this alteration and save the changes again.  The Tags/Categories pages should now work again, at least as long as the multi-page toolkit plug-in remains disabled or until the author fixes it.

Update: While the multi-page toolkit was the culprit on this blog, according to Luke this issue can be caused by other plug-ins also, especially those that alter tag/category links.  Luke’s WCS Custom Permalinks Hotfix page goes into more detail in preparing for the fix and about other potential culprits.

Update 2 (15 May): One point Luke mentioned is that the PHP statement “$wp_rewrite->flush_rules();” can break permalinks, so for curiosity I searched the PHP files of the multi-page toolkit and found this line in the file “TA_multi_toolkit.php”.  So I commented it out, re-ran the live-site update trick and removed Luke’s functions from the theme to check the outcome and now categories and tags are still working fine.  At the moment, this is how I left it on this blog as I’m curious to see if this has any side effect and so far everything seems to be working fine.

Here are the steps to fixing the multi-page toolkit:

  1. In your server’s hosting file browser (or FTP), go into wp-content/plugins/multi-page-toolkit and edit the file TA_multi_toolkit.php.
  2. Search for the line “$wp_rewrite->flush_rules();” and comment it out by adding ‘//’ to the start of the line and save the change:

    Alternatively, download this zip file which where I’ve made this fix, extract the PHP file and replace your file with it:

  3. Now run the site address update trick as follows:
  4. In the wp-admin control panel, go into Settings->General.
  5. Modify the field “Side address (URL)” by adding a ‘1’ to it, e.g. on this blog this would become “http://www.ssdfreaks.com1” and click the “Save Changes” button.
  6. Change the field “Side address (URL)” back to what it was, e.g. on this blog this would become “http://www.ssdfreaks.com” and click the “Save Changes” button.
Clear your browser’s cache and check whether categories/tags are working.  If you are using Luke’s plugin/fix, you’ll need to disable/undo this to check the outcome.  If the categories/tags still break, then it’s likely something else (e.g. another plug-in/theme) is causing the problem, in which you’ll need to re-enable and continue using Luke’s fix.