Fixing URL Conflicts with Custom Post Types in WordPress

In WordPress, each custom post type uses a unique permalink structure. This structure is determined by the "rewrite slug", which helps WordPress figure out what content to show when a user visits a particular URL.

In most situations, the rewrite slug is automatically set to match the custom post type name. While you can modify it, doing so improperly may cause issues, such as broken links or inaccessible pages. The most common mistake is using the same slug for multiple post types or setting it to "/".

This guide will show you how to avoid these problems and keep your custom post types working as expected.

How WordPress Processes URLs

The rewrite rules array is a list of patterns used to recognize and handle URLs. When a user visits a URL, WordPress checks it against these rules and identifies which content to display by pulling a slug from the URL.

They are based on regular expressions that match parts of a URL to specific content. To make it clearer, consider the rule used for URLs of built-in posts and pages:

^/([^/]+)/?$

This rule tells WordPress to match any URL with the flat pattern, e.g.:

https://example.com/%POSTNAME%/
https://example.com/hello-world/

and retrieve the post that matches the title in the URL. To sum up, these rules act like a map, guiding WordPress to the relevant post, page, or custom post type item.

Sometimes, depending on your website’s configuration, different content types might follow the same URL pattern. In these cases, the rule that appears first in the rewrite rules list will take precedence and be applied.

How is the Rewrite Slug Defined?

There are multiple methods for defining a custom post type in WordPress. If you do not want to rely on plugins like ACF, Toolset, or Pods, you can directly add a code snippet using the register_post_type() function in your WordPress code.

function custom_post_type_registration() {
	 $args = array(
		'public' => true,
		'label' => 'Book',
		'supports' => array( 'title', 'editor', 'thumbnail' ),
		'rewrite' => array( 'slug' => 'publication' ),
	 );
	 register_post_type( 'book', $args );
}
add_action( 'init', 'custom_post_type_registration' );

Not declaring the 'rewrite' arguments causes WordPress to use the custom post type's slug name, which in this case is "book".

The code above will register a new "book" post type with permalinks looking like this:

https://example.com/publication/a-sample-cpt-permalink

What Happens When Rewrite Settings Conflict?

Some developers try to remove the base-slug by setting the rewrite slug to an empty string ('/'). Even though it may appear to work initially, this will overwrite the other rewrite rules and could cause unexpected problems, such as broken links, missing content, or incorrect pages being shown.

...
'rewrite' => array( 'slug' => '/' ),
...

When there is no rewrite slug for a CPT, WordPress can handle the situation in two ways, depending on the rewrite slug's priority. Either scenario will make some of your content unavailable.

It could end up treating pages and posts as custom post type items, leading to 404 errors.
Alternatively, it may ignore the custom post type's rewrite rules, causing the custom post type items to show 404 errors.

While this problem is fairly common, the official documentation does not mention it. As a result, resolving it can be tricky unless you have a solid understanding of how the permalink system works on the back-end.

How Rewrite Rules Disrupt Bricks & Elementor Editors?

Rewrite rule conflicts can also occur due to third-party plugins, and they can impact both the core WordPress functionality and other plugins. For example, removing a rewrite slug for a custom post type can prevent content editors like Bricks and Elementor from working properly.

There are many threads and support tickets where users report the "Invalid post type" error in Bricks or experience issues with Elementor, such as the editor getting stuck during loading.

Invalid post type in Bricks editor — "Invalid post type" error after clicking "Edit with Bricks"

"The preview could not be loaded" error in Elementor editor

While these problems are not always linked to permalinks, analysis of support reports across Google suggests that removing the rewrite slug is often the common cause.

Solving URL Conflicts with Custom Post Types

As previously mentioned, WordPress may encounter URL conflicts when a custom post type (CPT) shares a URL pattern with other content types.

The easiest way to fix URL conflicts is to make sure that WordPress uses the default configuration for rewrite settings. This ensures that every content type has its own unique permalink base.

If this does not completely solve the problem, you can still remove the permalink base for any custom post type. To do this, use a plugin that overrides the default URL structure. This way, you can adjust the slugs and permalinks without causing conflicts.

Change the Rewrite Slug to a Default or Unique Slug

To avoid these problems, always keep a unique slug when registering a custom post type. In simple terms, when you register a post type, you do not need to worry about it unless you want to use a different permalink base than the default, which is the name of the post type.

For example, if you are creating a "portfolio" section for your website, you should define a distinct URL structure like this

...
'rewrite' => array( 'slug' => 'portfolio' ),
...

Changing the rewrite slug is just one part of the process. You also need to flush the rewrite rules to make WordPress update its URL settings.

Permalink Manager

If you need greater control and flexibility with permalinks, consider using a permalink plugin to avoid conflicts between custom post types' URLs.

Permalink Manager can help resolve URL conflicts, especially if you need to duplicate the same permalink base for different post types or taxonomies. Here's how to fix it:

Restore the Original Rewrite/Permalink Settings
First, restore the original rewrite settings and make sure each post type and taxonomy has a unique permalink base (e.g., /product/, /product-category/, /shop/).
Overwrite the Original URLs with Custom Permalinks
To overwrite the original URLs with custom permalinks, you will need to use the Permastructure settings within the Permalink Manager. You can find step-by-step instructions for duplicating the permalink formats in a separate article

The plugin offers a variety of features, including redirect fallback. It is important to mention here that it also allows you to remove the permalink base from any custom post type or taxonomy, a feature that the built-in system does not support:

Furthermore, it allows you to duplicate rewrite slugs across multiple post types and taxonomies, which can be helpful for grouping your content by URLs.

Remove CPT Slugs from URLs Using Code Snippet

If you prefer not to install any plugins, you can use a simple code snippet to remove the rewrite base from custom post type URLs without altering any existing rewrite rules.

This simple code allows WordPress detect post types from URLs based on their post name. You do not need to adjust any custom post type settings, so there will be no conflict between the rewrite rules.

The first part of the code modifies how WordPress detects a "flat" URL that lacks a rewritten slug. Once active, it will look through posts, pages, and chosen custom post types to find the right match for the detected slug.

In the second part, the code modifies the custom post type's permalink by removing the original slug. This is done dynamically through the built-in permalink hook (post_type_link) that allows customization of single CPT URLs.

The simplest way to make this code work is to add the code snippet directly to your theme's functions.php file.

function pm_get_custom_post_types() {
	return array( 'cpt_1', 'cpt_2' );
}
function pm_rewrite_cpt_permalinks( $post_link, $post, $leavename, $sample ) {
	$custom_post_types = pm_get_custom_post_types();
	if ( ! empty( $post->post_type ) && in_array( $post->post_type, $custom_post_types ) ) {
		if ( $leavename ) {
			$post_link = home_url( "%{$post->post_type}%" );
		} else {
			$post_link = home_url( $post->post_name );
		}
		$post_link = user_trailingslashit( $post_link );
	}
	return $post_link;
}
add_filter( 'post_type_link', 'pm_rewrite_cpt_permalinks', 10, 4 );
function pm_parse_cpt_permalinks( $query ) {
	if ( ! $query->is_main_query() || 2 != count( $query->query ) || ! isset( $query->query['page'] ) ) {
		return;
	}
	if ( ! empty( $query->query['name'] ) ) {
		$query->set( 'post_type', array_merge( array( 'post', 'page' ), pm_get_custom_post_types() ) );
	}
}
add_action( 'pre_get_posts', 'pm_parse_cpt_permalinks' );

Permalinks can be tricky to manage, so this snippet might not work in every scenario. Other plugins or custom rules could change how permalinks are processed. Feel free to tweak it based on your WordPress setup.

Conclusion

Setting up custom post types can sometimes lead to issues with URLs. A common problem is unexpected 404 errors. These errors may occur if the rewrite slugs for your CPTs overlap with those already used by other content types.

WordPress uses specific rules to match URLs to content. If you change the slug wrongly, it can cause issues like 404 errors or displaying the wrong pages. To prevent them, keep the default rewrite settings or choose a unique slug when you register a custom post type.

If you need more control over your URLs, consider using plugins like Permalink Manager. These plugins help you adjust slugs without causing conflicts. You can also modify permalink structures by using code snippets, but make sure you test it first since it could interfere with other rules or plugins.

Updated on February 15, 2025 by Maciej Bis