How do I match query strings in a Netlify redirect?

Definition: Netlify query matching selects a redirect rule using conditions on the URL's query parameters, the name and value pairs after ?. In _redirects, those conditions sit between the source path and destination; in netlify.toml, they use the query field.

Key facts

As of 17 October 2026, Netlify documents the following behavior:

• Netlify's redirect options require an exact parameter set for query matching and document automatic query forwarding for status codes 200, 301, and 302.
• Netlify's redirects and rewrites documentation specifies that the first matching rule wins, with _redirects processed before netlify.toml.
• Netlify's rewrites documentation defines a 200 rule as a rewrite: the browser address stays the same while Netlify fetches the destination.

Where do query conditions go?

Netlify's configuration syntax places each _redirects rule on its own line. The file has no extension and belongs in the publish directory, the folder of finished files deployed by Netlify. A build must preserve that file in its output.

The alternative is a [[redirects]] table in netlify.toml. Its from field supplies the source path, to supplies the destination, and query supplies required query conditions. The status field defaults to 301. For example, the query condition in the next section can be written as query = { id = ":id" } within a redirect table.

How does an exact parameter match work?

Netlify's query parameter example captures an id value and inserts it into the destination path:

/store id=:id  /blog/:id  301

This matches /store?id=my-blog-post and redirects to /blog/my-blog-post. An additional parameter prevents this particular rule from matching. Multiple required parameters are written as separate, space-separated pairs.

For optional parameters, the same documentation supplies separate rules for each combination, followed by a general fallback:

/path/* param1=:value1 param2=:value2 /otherpath/:value1/:value2/:splat 301
/path/* param1=:value1 /otherpath/:value1/:splat 301
/path/* param2=:value2 /otherpath/:value2/:splat 301
/path/* /otherpath/:splat 301

Here * captures the remaining path for substitution through :splat. The browser's parameter order does not affect the combined match. The final rule handles requests left unmatched by earlier rules.

When are query parameters forwarded?

Netlify's redirect options state that query strings pass automatically to destination paths for 200, 301, and 302 rules. In the fallback above, the documentation explicitly says that a general rule used alone forwards all query parameters.

A 200 rule still serves a different destination behind the original browser URL, as Netlify's rewrites documentation explains. Checking the address bar alone therefore cannot show the destination of a rewrite.

How can the rules be checked locally?

Netlify's local development guide describes Netlify Dev, a local proxy that includes redirect logic. After installing and authenticating the command-line tool and linking the project, the documented command runs from the repository root:

netlify dev

A useful check covers the combined parameters, each single parameter, and the fallback in the example above. The guide directs readers to the console output for the local server address. Requests must reach that Netlify Dev address to exercise its redirect logic.

Related terms

• URL parameters
• HTTP redirects
• How do I add redirects with Netlify's _redirects file?
• How do I redirect a URL directory on Netlify?

FAQ

Why does adding a tracking parameter stop my rule matching?

Netlify requires the parameter set to match exactly. You can add a rule covering that combination before the general fallback.

Can a rule in netlify.toml take priority over _redirects?

Netlify processes _redirects first. You must account for an earlier matching rule there when configuring netlify.toml.

Sources

1. Netlify, "Redirect options", 17 September 2026
2. Netlify, "Redirects and rewrites", 14 July 2025
3. Netlify, "Rewrites and proxies", 14 July 2025
4. Netlify, "Local development with Netlify CLI", 19 November 2025

---

Check how a page reads to answer engines. Open the GEO score analyzer