customization - Custom post type defaults to index.php for archive page

I've developed a custom theme with a custom post type named events. For some reason, however, WP refuses to use my archive page template with the file name archive-events.php per WP's template hierarchy. WP keeps defaulting to index.php as the template for this post type.

Previously I had a page configured in WP that was set to the slug /events/ which is now the slug of the custom post type. That page is now deleted, and I don't know if this is the issue that is causing WP to refuse to use archive-events.php for my archive listing for the custom post type. I've tried modifying and re-saving my permalink structure, and that hasn't worked. Currently the permastruct is set to "Post name," i.e. /post-name/

More details:

• I've registered a custom post type of events (code below)
• The slug of the post type is "events" and individual posts are rendering successfully at
• The archive page for the post type is accessible at /events/ but is using index.php even though I've created an archive template for the post type as archive-events.php
• To confirm what template WP is using to render the archive page for the custom post type, I've created a function that outputs the $GLOBALS['current_theme_template'] being used to render the page. This confirms that WP is using index.php to render the archive page.
• In my header.php file I'm echoing the function get_post_type_archive_link('events') to confirm that WP thinks that the archive page for my custom post type should be /
• The archive.php and index.php WP templates are served as expected, but the template for the custom post type is skipped by WP no matter what
• As a test, I renamed my existing custom post type to something new, remapped all of my queries to that CPT, and updated my template names accordingly. Still, WP refuses to serve cpt-archive.php as the template for the custom post type and serves either archive.php or index.php instead.

Here's my functions.php code to register the post type:

function registerEvents()
{
    $labels = array(
        'name'                  => _x( 'Events', 'Post type general name', 'textdomain' ),
        'singular_name'         => _x( 'Event', 'Post type singular name', 'textdomain' ),
        'menu_name'             => _x( 'Events', 'Admin Menu text', 'textdomain' ),
        'name_admin_bar'        => _x( 'Events', 'Add New on Toolbar', 'textdomain' ),
        <snip>
    );
    $args = array(
        'labels'                => $labels,
        'public'                => true,
        'hierarchical'          => false,
        'publicly_queryable'    => true,
        'exclude_from_search'   => false,
        'show_ui'               => true,
        'show_in_menu'          => true,
        'show_in_rest'          => false,
        'menu_position'         => 5,
        'menu_icon'             => 'dashicons-calendar-alt',
        'capability_type'       => 'post',
        'has_archive'           => true,
        'query_var'             => true,
        'delete_with_user'      => false,
        'supports'              => array( 
            'title',
            'editor',
            'excerpt',
            'thumbnail',
            'page-attributes'
        ),
        'taxonomies'            => array( 'kind' ), // Custom tax previously registered
        'rewrite'               => array( 'slug' => 'events', 'with_front' => false ),
    );
    register_post_type( 'events', $args );
}
add_action( 'init', 'registerEvents' );

I've developed a custom theme with a custom post type named events. For some reason, however, WP refuses to use my archive page template with the file name archive-events.php per WP's template hierarchy. WP keeps defaulting to index.php as the template for this post type.

Previously I had a page configured in WP that was set to the slug /events/ which is now the slug of the custom post type. That page is now deleted, and I don't know if this is the issue that is causing WP to refuse to use archive-events.php for my archive listing for the custom post type. I've tried modifying and re-saving my permalink structure, and that hasn't worked. Currently the permastruct is set to "Post name," i.e. http://my.domain/post-name/

More details:

• I've registered a custom post type of events (code below)
• The slug of the post type is "events" and individual posts are rendering successfully at http://domain.com/events/post-name
• The archive page for the post type is accessible at /events/ but is using index.php even though I've created an archive template for the post type as archive-events.php
• To confirm what template WP is using to render the archive page for the custom post type, I've created a function that outputs the $GLOBALS['current_theme_template'] being used to render the page. This confirms that WP is using index.php to render the archive page.
• In my header.php file I'm echoing the function get_post_type_archive_link('events') to confirm that WP thinks that the archive page for my custom post type should be http://domain.com/events/
• The archive.php and index.php WP templates are served as expected, but the template for the custom post type is skipped by WP no matter what
• As a test, I renamed my existing custom post type to something new, remapped all of my queries to that CPT, and updated my template names accordingly. Still, WP refuses to serve cpt-archive.php as the template for the custom post type and serves either archive.php or index.php instead.

Here's my functions.php code to register the post type:

function registerEvents()
{
    $labels = array(
        'name'                  => _x( 'Events', 'Post type general name', 'textdomain' ),
        'singular_name'         => _x( 'Event', 'Post type singular name', 'textdomain' ),
        'menu_name'             => _x( 'Events', 'Admin Menu text', 'textdomain' ),
        'name_admin_bar'        => _x( 'Events', 'Add New on Toolbar', 'textdomain' ),
        <snip>
    );
    $args = array(
        'labels'                => $labels,
        'public'                => true,
        'hierarchical'          => false,
        'publicly_queryable'    => true,
        'exclude_from_search'   => false,
        'show_ui'               => true,
        'show_in_menu'          => true,
        'show_in_rest'          => false,
        'menu_position'         => 5,
        'menu_icon'             => 'dashicons-calendar-alt',
        'capability_type'       => 'post',
        'has_archive'           => true,
        'query_var'             => true,
        'delete_with_user'      => false,
        'supports'              => array( 
            'title',
            'editor',
            'excerpt',
            'thumbnail',
            'page-attributes'
        ),
        'taxonomies'            => array( 'kind' ), // Custom tax previously registered
        'rewrite'               => array( 'slug' => 'events', 'with_front' => false ),
    );
    register_post_type( 'events', $args );
}
add_action( 'init', 'registerEvents' );

• custom-post-types
• customization
• permalinks
• templates

Share Improve this question edited Mar 17, 2020 at 12:53 strangeattractor asked Mar 16, 2020 at 21:22 strangeattractorstrangeattractor 133 bronze badges 7

• Does your post type have any posts? And do you have a default archive.php? Because the hierarchy should hit that before the index. – vancoder Commented Mar 16, 2020 at 21:56
• The custom post type currently has 5 posts. I don't currently use archive.php because I have blog posts that will need to have a different output format. That said, I can try renaming my current custom post type archive page from archive-events.php to archive.php and see what happens. – strangeattractor Commented Mar 16, 2020 at 22:10
• Renaming my existing archive-events.php template for the custom post type to archive.php displays a page, but I'll have to recode archive.php completely to fetch posts within the custom post type. I'd still like to understand why WP refuses to use the archive-events.php template per WP's template hierarchy. – strangeattractor Commented Mar 16, 2020 at 22:13
• Possibly a dumb question, but you said you deleted the old page. Did you empty trash? My first thought was actually that you need to flush your permalinks, but it sounds like you did that already. – vancoder Commented Mar 16, 2020 at 22:22
• As an experiment, I would try renaming your CPT (eg events2). Rename your custom archive, flush your permalinks, and see if it kicks in. If it does, that would point to the issue being related to the old page address being cached somewhere. – vancoder Commented Mar 16, 2020 at 22:31

 |  Show 2 more comments

2 Answers 2

Sorted by: Reset to default 0

The solution to this problem turned out to be:

• Changing the name of the custom post type from "events" (with the slug /events/) to "event" (with the slug /event/)
• Creating a page with a custom template with the slug /events/ to display the archives of the custom post type

While this is technically not an answer to the question of why WP refuses to serve and display the archive template for the custom post typer per WP's own template hierarchy, it solves my problem.

Along the way, I used wp-cli to flush WP's internal cache and delete all transients, but that didn't have any effect.

If you're registering post types manually (as opposed to using CPT UI or something similar) then you need to remember to go into settings > permalinks and just click 'save'. That's caught me out a couple of times.