Custom post type defaults to index.php for archive page

Question

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' );

Answer 1

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.

Answer 2

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.