Pagination broken by naming conflict between CPT and Page

Question

I have run into this issue before with pagination where your custom post type is called something like 'insights' and then the page that you create to display those custom posts in an archive is called 'insights' too. Straight away there is a naming conflict. When WordPress searches for the second page it actually searches the page 'insights' instead of the post type 'insights' and of course it returns a 404 not found error. Just to double check I have changed the name of the page on my local and sure enough pagination worked.

The problem I have is that I can't just rename the page to something else because that is out of my hands (unless it is the only way) and their are hundreds of posts so I can't just rename the post type. So based on my code below is there anything I can change to fix this in code?

<?php
/*
    Template name: Insights
*/      

get_header();
the_post();
$insights = get_field('insights');
$filters = array();

// Category
if( isset($_GET['insights_category']) && $_GET['insights_category'] != 0 ) {
    $filters[] = array(
        'taxonomy'  => 'insights_category',
        'field'     => 'id',
        'terms'     => $_GET['insights_category']
    );
}

$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
$insights = new WP_Query(array(
    'post_type' => 'insights',
    'post_status' => 'publish',
    'order' => 'DESC',
    'tax_query' => $filters,
    'posts_per_page' => 9,
  'paged' => $paged
));

?>

<?php echo get_template_part('content', 'utility-bar'); ?>

<div class="nine">
    <!-- Display the Page's Content in a div box. -->
    <div class="entry">
        <h2><?php the_title(); ?></h2>
        <?php echo get_template_part('content', 'description'); ?>
    </div>
    <div class="borderEntry"></div>

<?php /*
???
    <div class="content-landing box" >
        <?php the_content(); ?>
    </div>
*/ ?>

    <div id="insights_main">
        <?php
        if ($insights->have_posts()) :
            while( $insights->have_posts() ) :
                $insights->the_post();
        ?>
            <div class="insights_content">
                <h4><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h4>
                <div class="insights_meta">
                    Posted on <?php the_time('F j, Y \a\t g:i a'); ?>
                    <?php
                        $tags = wp_get_post_terms( $post->ID, 'insights_tag');
                        if ($tags) {
                            echo ' | ';
                            $i = 1;
                            $last = count($tags);
                            foreach ($tags as $tag) {
                                echo '<a href="/' . $tag->taxonomy . '/' . $tag->slug . '">' . $tag->name . '</a>';
                                if ($i < $last) {
                                    echo ', ';
                                }
                                $i++;
                            }
                        }
                    ?>
                </div>
                <div class="isights_img">
                    <?php if (has_post_thumbnail()): ?>
                        <?php the_post_thumbnail(); ?>
                    <?php else:?>
                        <img src="<?php echo get_template_directory_uri(); ?>/images/web/default-people.png" alt=" " />
                    <?php endif; ?>
                </div>
                <div class="insights_excerpt">
                    <?php the_excerpt(); ?>
                </div>
                <div class="insights_excerpt_bottom">
                    <div class="insights_social">
                        <a href="https://twitter.com/intent/tweet?url=<?php the_permalink(); ?>&text=<?php the_title(); ?>" class="insights_twitter"></a>
                        <a href="https://facebook.com/sharer.php?u=<?php the_permalink(); ?>" class="insights_facebook"></a>
                        <a href="https://plus.google.com/share?url=<?php the_permalink(); ?>" class="insights_gplus"></a>
                        <a href="http://www.linkedin.com/shareArticle?mini=true&url=<?php the_permalink(); ?>&title=<?php the_title(); ?>" class="insights_linkedin"></a>
                        <a href="mailto:?subject=<?php the_title(); ?>&body=<?php the_permalink(); ?>" class="insights_email"></a>
                    </div>
                    <a class="insights_more" href="<?php the_permalink(); ?>">Read more →</a>
                </div>
            </div>
            <div class="border-bottom"></div>

            <?php endwhile; ?>

      <div class="nav-previous alignleft"><?php next_posts_link( 'Older posts', $insights->max_num_pages ); ?></div>
      <div class="nav-next alignright"><?php previous_posts_link( 'Newer posts', $insights->max_num_pages ); ?></div>

        <?php else: ?>
            <div class="insights_content">
                <p>No insights post matches your selected criteria.</p>
                <p>Please try your search with different criteria, or <a href="<?php echo get_template_directory_uri(); ?>/insights/">view all insights posts</a>.</p>
            </div>
            <div class="border-bottom"></div>
        <?php endif; ?>
    </div>

  <?php wp_reset_postdata(); ?>

  <?php require 'tpl-insights-right-menu.php'; ?>
</div>

<?php get_footer(); ?>

Answer 1

You can add a rewrite rule to override the post type rules and force it to load your page.

function wpd_fix_insights_pagination(){
    add_rewrite_rule(
        'insights/page/([0-9]+)/?$',
        'index.php?pagename=insights&paged=$matches[1]',
        'top'
    );
}
add_action( 'init', 'wpd_fix_insights_pagination' );

Visit your Settings > Permalinks admin page after adding this code to flush rewrite rules.