You registered the custom post type. You built an archive template, named the file with surgical precision, and dropped it into your theme. Then you hit refresh. Nothing. Instead of your layout, you get the generic index.php—or worse, a 404. The slug looks right. The filename matches. The query seems fine. WordPress just ignores your template. It’s not a bug. It’s a quiet mismatch between what you meant and what the template loader actually sees, usually hiding inside rewrite rules, query variables, or some tiny config flag you swore you double-checked. Let’s walk through exactly why this happens and what to fix, from the server config down to the PHP that picks your template file.

The Template Hierarchy Is a Promise, Not a Magic Trick

Most WordPress builders learn the hierarchy early. For a custom post type “book,” the archive template should be archive-book.php. The diagram says so. The promise is simple: if that file exists, WordPress uses it. The catch? The hierarchy only kicks in when WordPress correctly recognizes the request as a post type archive in the first place. If it doesn’t, your perfectly named file just sits there while the system falls back to something generic. The root cause is rarely the hierarchy itself. It’s the setup that leads into it.

The template loader fires after the main query gets parsed. During template_redirect, WordPress decides what kind of page it’s dealing with, based on query variables. For a post type archive, the key variable is post_type. If that variable isn’t set—or gets overwritten—is_post_type_archive() returns false, and your archive template never loads. This disconnect happens a lot on sites with custom rewrite structures, plugins that intercept queries, or post types registered without real attention to the archive setting.

Check the Basics: The has_archive Parameter

When you call register_post_type(), the has_archive argument controls whether an archive page even exists. Set it to false (or skip it, since false is the default) and WordPress won’t generate archive rewrite rules. Visiting /book/ then gives a 404, and no template is ever consulted. Plenty of developers set has_archive => true but still hit trouble because they think the archive slug always matches the post type slug. It does, but only if you don’t specify a string. If you write has_archive => 'books', the archive lives at /books/, but your template file still must be archive-book.php—named after the post type, not the slug. Get those two crossed and nothing lines up.

A fast check: visit the archive URL right after flushing rewrite rules. If you get a 404, the archive isn’t registered right. Go back to your register_post_type() call. Make sure has_archive is either true or a slug string. Then flush permalinks by visiting Settings > Permalinks and clicking Save Changes. That rebuilds the rewrite rules and often fixes things on the spot.

Rewrite Rules and the Query Variable Chain

Every pretty permalink relies on a rewrite rule that maps the URL to query variables. For a post type archive, the rule usually matches the archive slug and sets post_type accordingly. You can inspect your rules with a plugin like Rewrite Rules Inspector or by dumping the $wp_rewrite global. Look for a rule matching your archive slug. If it’s missing, the registration is broken. If it’s there but points to the wrong query var, something else—a plugin or custom code—is interfering.

Sometimes a plugin registers its own rules that collide with yours. A membership plugin might grab the same slug and redirect to a login page. Your archive template never loads because the request gets intercepted earlier. Debugging this means disabling plugins one by one or using Query Monitor to see which rules actually match.

When Your Archive Template Is Named Wrong

The hierarchy for custom post type archives is straightforward: archive-{post_type}.php. But the post type is the internal name—the first argument to register_post_type()—not the rewrite slug or the label. If you registered the post type as cpt_book but the archive slug is books, the template file must be archive-cpt_book.php. Naming it archive-books.php fails. This trips people up when the post type name gets abstracted or generated by a plugin.

Also, watch for typos and case. Most servers treat file names as case-sensitive, so Archive-Book.php won’t match. WordPress looks for the exact lowercase string from the post type name. If you’re on a child theme, make sure the file sits in the child theme directory. The hierarchy searches the child theme first, then the parent. A file in the parent still works if the child theme misses it. But a mismatch in naming doesn’t.

Archive vs. Custom Page Template Confusion

Some developers sidestep the archive entirely and use a page template instead. They create a “Books” page, assign a custom template, and run a WP_Query loop. That works, but it ignores the main query and the template hierarchy. The actual archive endpoint still exists, often leading to duplicate content or confusion. If you genuinely want an archive, use the built-in one. If you need extra content above the loop, think about filtering archive_template or using the template_include filter to load a custom file only when is_post_type_archive('book') is true. That keeps the main query intact and avoids the performance hit of secondary queries.

The Main Query vs. Custom Queries

WordPress runs a main query on every request, based on the URL. That query sets up the global $wp_query object and all the conditional tags. Your archive template depends on that main query. If you or a plugin swap the main query with a custom WP_Query via pre_get_posts, you might accidentally alter the post type parameter. For example, setting $query->set('post_type', 'any') on an archive page can break the conditional tag because the post type is no longer singular. The template hierarchy might still load the archive file, but the loop inside could go sideways.

A subtler mess happens when a plugin uses query_posts()—a function that overwrites the main query entirely and should be avoided. If query_posts() runs before the template loader, it resets query variables, making WordPress think it’s no longer an archive page. The fix: rip out that call and use pre_get_posts to modify the main query safely.

If you’re building a custom archive page that needs extra queries, always use new WP_Query() for secondary loops and call wp_reset_postdata() afterward. That preserves the main query’s state and keeps your template working.

Flushing Rewrite Rules: The Silent Fix

After registering a custom post type, WordPress needs to rebuild its rewrite rules. This doesn’t happen on every page load—that’s a performance choice. The rules live in the database and only regenerate when you flush them. The easiest way: visit the Permalinks settings page. Just loading wp-admin/options-permalink.php triggers a flush. You don’t need to change anything.

During development, some people call flush_rewrite_rules() on every load. That’s expensive. Flush only on plugin activation or theme switch instead. If you’re debugging, flush manually. If your archive still breaks after a flush, the problem lies deeper.

Checking Query Variables with a Debugging Tool

Sometimes you need to see exactly what WordPress thinks it’s doing. The Query Monitor plugin is indispensable here. It shows the main query’s request, the matched rewrite rule, the query variables, and the template file being loaded. If your archive template isn’t loading, Query Monitor tells you which template is used instead and why. Look at the “Request” section. If it says “None,” your rewrite rule isn’t recognized. If it shows a different rule, you’ve got a conflict.

You can also dump query variables in your theme’s functions.php during debugging:

add_action('template_redirect', function() {
    if (is_post_type_archive('book')) {
        var_dump($GLOBALS['wp_query']->query_vars);
    }
});

This outputs the query variables on the archive page, confirming whether post_type is set correctly. Remove it before going live.

Plugins That Hijack Archives

SEO plugins, caching layers, and security tools all mess with how WordPress handles requests. Some SEO plugins add trailing slashes or redirect archives to a different URL structure. A caching plugin might serve a stale 404 page from before you fixed the rewrite rules. Clear your cache after any change to permalinks or post type registration. If a security plugin blocks direct access to certain URL patterns, it might intercept your archive slug.

Membership and LMS plugins often register their own post types and archives, sometimes with broad rewrite rules that catch your slug. If your archive slug is courses and LearnDash is active, expect a conflict. The fix: change your archive slug to something unique, or use a filter to adjust rewrite rule priority.

A related problem: a plugin uses template_include to force a specific template file for all post type archives. If the plugin’s logic runs after yours, it overrides your template. Check the list of filters on template_include to see which one returns a different path.

When the Archive Page Shows a 404 Despite Everything Being Correct

You’ve confirmed has_archive is true, flushed rewrites, disabled conflicting plugins, and named your template file correctly. Yet /book/ still returns a 404. This can happen when the post type itself isn’t publicly queryable. The publicly_queryable parameter in register_post_type() defaults to the value of public. If you set public => false but still want an archive, you must explicitly set publicly_queryable => true and has_archive => true. Otherwise, the archive is registered but hidden from the front end.

Another 404 cause: a mismatch between the archive slug and the post type rewrite slug. If you set rewrite => array('slug' => 'library') for a post type book, the single post URL becomes /library/book-name/. But the archive slug is still controlled by has_archive. If you set has_archive => 'books', the archive lives at /books/, not /library/. Some developers expect the rewrite slug to affect the archive—it doesn’t. If you want the archive at /library/, set has_archive => 'library'. Watch out for collisions with page slugs.

Multisite and Custom Post Type Archives

On a WordPress multisite network, custom post types are often registered per site. If you activate a theme or plugin network-wide, the registration happens everywhere, but rewrite rules are site-specific. You need to flush rewrite rules on each site that uses the post type. Visit the Permalinks page on each site. Some plugins handle this automatically; many don’t. If your archive works on the main site but not on a subsite, this is probably why.

Also, the main site’s rewrite rules can affect subsites if they share the same URL structure. A post type registered on the main site with an archive slug of blog might conflict with a subsite’s default blog path. Rare, but worth checking when you see unexpected 404s.

Polylang, WPML, and Multilingual Archives

Multilingual plugins add a layer of complexity to the template hierarchy. They often modify the query to filter by language and may change the archive slug to include a language prefix. For example, /books/ becomes /en/books/. The template hierarchy still uses archive-book.php, but the query variables now include a language parameter. If the plugin doesn’t properly set the post_type query variable, the archive template won’t load. You might need the plugin’s API to force the correct template or adjust rewrite rules to handle the language prefix.

Some multilingual plugins also register their own rewrite rules for post type archives. If your template isn’t loading, check the plugin’s settings for an option controlling archive handling. Sometimes you just need to resave the plugin’s permalink settings after registering a custom post type.

Custom Post Type Archives and the Front Page

A less common but confusing scenario: your archive slug is empty or set to front. If you set has_archive => false and then create a page with the same slug as the post type, WordPress can get confused. More often, developers try to set the archive as the front page by using has_archive => true and then configuring a static front page. The archive still exists at its slug, but the front page uses a different template. If you want the archive to be the front page, use pre_get_posts to modify the main query on the front page—not the template hierarchy. This is an advanced setup that requires careful handling of page_on_front and show_on_front options.

Programmatic Template Overrides

For sites that need more control, the template_include filter lets you load a specific file based on conditions. This partially bypasses the template hierarchy, but it’s explicit and predictable. Here’s an example that loads a custom file for a book archive:

add_filter('template_include', function($template) {
    if (is_post_type_archive('book')) {
        $custom_template = locate_template('custom-book-archive.php');
        if ($custom_template) {
            return $custom_template;
        }
    }
    return $template;
});

This approach helps when multiple post types need the same archive layout, or when you want to load a template from a plugin directory. The template hierarchy still runs; you’re just overriding its choice at the last moment.

Another filter, archive_template, is more specific—it fires only for archive pages. It receives the current template path and expects a path in return. A cleaner hook if you’re only targeting archives.

What to Do When Everything Fails

If you’ve checked all the above and your archive template still won’t load, step back and test in isolation. Switch to a default WordPress theme like Twenty Twenty-Four. Deactivate all plugins except the one registering the post type. Flush rewrite rules. Create a minimal archive-{posttype}.php file in the theme with just a header and a loop. If it works, the issue is a conflict with your theme or another plugin. Re-enable them one by one until it breaks. This binary search method isolates the culprit fast.

Also, check your server configuration. Rarely, a server-level rewrite rule (in .htaccess or Nginx config) intercepts the URL before WordPress processes it. If you’re on Nginx, make sure the standard WordPress rules are in place and that nothing else is grabbing the request.