Every single WordPress tag is returning a 404 error

That tag “stuff” is not working on our corporate website, please fix asap the costumer complained. Sure, will do immediately I replied confidently, believing this to be a simple matter of purging some old cache or refreshing permalinks. Sadly that was not to be the case so I ended up having to get my hands dirty. To my absolute horror, the site was running one of those godawful themeforest themes.

To investigate further I turned on debugging, including “SAVEQUERIES” and quickly spotted issues with a couple of queries:

SELECT t.*, tt.* FROM wp_terms AS t
INNER JOIN wp_term_taxonomy AS tt ON t.term_id = tt.term_id
WHERE tt.taxonomy IN ('staff_tag') AND t.slug = 'events' LIMIT 1

SELECT wp_term_taxonomy.term_taxonomy_id
FROM wp_term_taxonomy
INNER JOIN wp_terms USING (term_id)
WHERE taxonomy = 'staff_tag'
AND wp_terms.slug IN ('events')

Those WHERE statements were not exactly what I expected in regard to the taxonomy clause. We’re pulling posts after all, so the correct taxonomy would have been ‘post_tag’ and not ‘staff_tag’.

Let’s have a look at how the URL https://site.tld/tag/events/ is being processed (using “month and name” permalinks):

request: tag/events
rewrite rule: [tag/([^/]+)/?$] => index.php?staff_tag=$matches[1]
query string: staff_tag=events

The following is the expected default behavior:

request: tag/events
rewrite rule: [tag/([^/]+)/?$] => index.php?tag=$matches[1]
query string: tag=events

After examining the rewrite_rules stored in the wp_options table, I could conclude that the site no longer had the default WordPress rewrite rules used for tags. They had all been replaced by the ‘staff_tag’ taxonomy.

This mishap turned out to be caused by the theme’s inclusion of a few custom post types supporting custom taxonomies. When enabling the tag functionality, the webmaster had to pick a slug (and yes he picked tag) and thus unknowingly replaced the default WordPress rewrite rules.

However, I don’t blame the webmaster as the theme author should not have allowed the use of reserved terms (like tag) with custom taxonomies. The WordPress codex explicitly warns developers against this practice.

Anyhow, after getting rid of them “bad slugs” the theme and site returned to normal.