- Article
- 3 minutes read
- Reviewed August 3, 2026
Rewrite rules translate readable WordPress URLs into internal query variables. They allow a request such as /events/summer-festival/ to become a query for an Event record with a particular slug.
Most custom content URLs are generated through post type and taxonomy registration. Custom rules are needed only when the required route cannot be expressed by standard arguments.
How WordPress Rewrites Work
WordPress generates an ordered set of patterns. When a request arrives, it tests the path against those patterns and populates query variables for the main query.
The theme or template loader then renders the result. A rewrite rule does not itself output a page.
Registration-Generated Rules
The rewrite arguments of register_post_type() and register_taxonomy() generate common single and archive routes.
Prefer these standard mechanisms because they integrate with permalink generation, template queries and the wider WordPress ecosystem.
Adding a Custom Rule
Developers can use add_rewrite_rule() for special routes. The rule maps a regular-expression pattern to an internal WordPress query.
add_action( 'init', function () {
add_rewrite_rule(
'^events/([0-9]{4})/?$',
'index.php?post_type=event&event_year=$matches[1]',
'top'
);
} );The custom query variable must also be recognized, and the query logic must interpret it. A rule alone is incomplete.
Flushing Rewrite Rules
New or changed rules must be regenerated before WordPress can use them. Visiting Settings → Permalinks and saving refreshes the rules.
Plugins should flush rules on activation or another controlled migration event, not on every request. Repeated flushing is expensive and can create concurrency problems.
Rule Order and Conflicts
Rewrite patterns are evaluated in order. A broad rule can capture paths intended for a more specific page, taxonomy or endpoint.
Use the narrowest pattern required and inspect the generated rules when debugging.
Server Configuration
WordPress rewrites depend on the web server forwarding appropriate requests to WordPress. Apache commonly uses .htaccess; Nginx uses server configuration.
A correct WordPress rule cannot compensate for a server that never passes the request to WordPress.
Debugging 404 Errors
- Confirm that the post type or taxonomy is registered on every request.
- Confirm that public query and rewrite settings are enabled.
- Refresh rewrite rules once.
- Check for page, taxonomy and endpoint slug conflicts.
- Inspect generated rules with a debugging tool or WP-CLI.
- Confirm the server permalink configuration.
- Check language, multisite and trailing-slash behaviour.
Avoiding Fragile Routes
Do not create complex URLs merely to reproduce a database hierarchy. Every dynamic segment increases ambiguity, migration cost and testing requirements.
A stable shallow URL often provides better long-term maintainability.
Redirects Are Separate
Rewrite rules decide how current WordPress routes resolve. Redirects send visitors and search engines from an old URL to a new one.
Changing a slug generally requires both updated rewrites and explicit redirects.
Rewrite Rule Principles
- Use registration arguments before custom regular expressions.
- Flush rules only on activation or controlled changes.
- Register required query variables.
- Test rule order and collisions.
- Debug the server and WordPress layers separately.
- Add redirects for moved public URLs.
Frequently Asked Questions
Should I flush rewrite rules on init?
No. Register rules on init, but flush only during controlled lifecycle events because flushing on every request is expensive.
Are rewrite rules redirects?
No. Rewrites map a public path to an internal WordPress query. Redirects return an HTTP response that sends the client to another URL.
Why does saving Permalinks fix a 404?
Saving regenerates the stored rewrite rules so newly registered routes become available.