Fix default post type for custom taxonomy terms in WordPress admin

by

How to Fix Wrong Default Post Type for Custom Taxonomy Term in WordPress Admin

Summary

When building custom post types with custom taxonomies in WordPress, clicking on a taxonomy term in the admin area often directs users to the wrong post type—defaulting to the built-in “Posts” instead of your custom post type. This creates a confusing user experience where administrators expect to see their custom post type entries but instead see standard posts. The root cause lies in how WordPress handles URL query parameters when post_type is not explicitly specified in admin links.

Root Cause

WordPress defaults to the post post type when no post_type query parameter is present in admin URLs.

When you register a custom taxonomy and WordPress generates the edit tags page, the links created for each term include the taxonomy parameter but omit the critical post_type parameter:

  • Generated link: /wp-admin/edit.php?taxonomy=domain&term=some-term
  • Expected link: /wp-admin/edit.php?post_type=model&taxonomy=domain&term=some-term

The WordPress edit.php handler checks for $_GET['post_type']. If absent, it defaults to 'post'. This behavior is hardcoded in the WordPress core and affects any custom taxonomy not explicitly tied to the default posts post type.

Why This Happens in Real Systems

  • Taxonomy registration order matters — When taxonomies are registered before their associated post types, WordPress may not properly associate them in admin URL generation
  • Custom menu additions — Using add_submenu_page() to create custom taxonomy admin menus often bypasses the automatic post type linking that happens with built-in menus
  • Hierarchical vs non-hierarchical confusion — Non-hierarchical custom post types behave differently than hierarchical ones in URL generation
  • Multiple post type associations — When a taxonomy is registered with multiple post types, WordPress cannot determine which one to display by default

Real-World Impact

  • Confused administrators — Users clicking on taxonomy terms see unrelated content
  • Broken workflow — Content managers cannot efficiently navigate between taxonomy terms and associated posts
  • Data integrity concerns — Users may accidentally edit or delete wrong post types
  • Support overhead — Development teams receive tickets about “broken” admin functionality
  • Poor user experience — This undermines confidence in custom WordPress solutions

Example or Code

The issue manifests when WordPress generates these links in the term list table:

// What WordPress generates (incorrect)
$link = 'edit.php?taxonomy=domain&term=' . $term->slug;

// What should be generated (correct)
$link = 'edit.php?post_type=model&taxonomy=domain&term=' . $term->slug;

The fix requires filtering the admin URL or explicitly setting the post type in the taxonomy registration:

// Add post_type to taxonomy admin URLs
add_filter('term_link', function($termlink, $term, $taxonomy) {
    if ($taxonomy->name === 'domain') {
        $termlink = add_query_arg('post_type', 'model', $termlink);
    }
    return $termlink;
}, 10, 3);

How Senior Engineers Fix It

Senior engineers address this at multiple levels:

  • Filter term_link — Modify the generated term URLs to include the correct post_type parameter before output
  • Filter post_type_link — Ensure the reverse relationship also works correctly
  • Use register_taxonomy arguments properly — Set the object_type parameter correctly in taxonomy registration
  • Admin menu hook customization — Override the admin menu URL generation for custom taxonomies
  • Custom admin page creation — Build a dedicated admin page for taxonomy-term-to-post associations instead of relying on WordPress defaults
  • Add query vars to pre_get_posts — Intercept the main query in admin and force the correct post type

The most robust solution combines filtering term_link with ensuring proper taxonomy-post-type association during registration:

add_filter('term_link', function($url, $term) {
    if ($term->taxonomy === 'domain') {
        $url = remove_query_arg('post_type', $url);
        $url = add_query_arg('post_type', 'model', $url);
    }
    return $url;
}, 10, 2);

Why Juniors Miss It

  • Assuming WordPress handles everything automatically — Juniors often trust that core WordPress functions work correctly out of the box
  • Not reading core source code — The default post type behavior is documented in wp-admin/edit.php but rarely examined
  • Testing only happy paths — They test taxonomy creation and post association but not the navigation links between them
  • Ignoring admin URL structure — The difference between edit.php?taxonomy=x and edit.php?post_type=y&taxonomy=x is subtle but critical
  • No understanding of query parameter precedence — Many juniors don’t realize WordPress uses $_GET parameters to determine admin behavior
  • Copy-pasting from tutorials — Many WordPress tutorials skip over this edge case entirely

The fix is a single line of code, but identifying the problem requires understanding WordPress admin routing deeply.

Leave a Comment