A collision occurs when WordPress rewrite rules allow the same request path to represent more than one resource, such as a page and a custom post type single. ThemeRouter 1.1.0 includes deterministic safeguards for these conflicts.
Identify a collision
- The URL unexpectedly returns a 404 even though both resources exist.
- A page and custom post type use the same slug or rewrite base.
- Changing permalink rules changes which resource appears.
- Debug output reports competing page and custom post type candidates.
Preferred resolution
Give each public resource a unique canonical path. Adjust the page slug, custom post type rewrite base, or content architecture, then flush rewrite rules by resaving Settings > Permalinks.
Developer-controlled resolution
When URLs cannot be changed, developers can use themerouter_collision_precedence for equal-precedence ties or themerouter_collision_conflict_resolution for exact ambiguous conflicts. Review the developer reference and test all related routes before deployment.
The default for an exact ambiguous page and custom post type single conflict is intentionally conservative. Do not force a winner without confirming canonical URLs, redirects, and SEO implications.