How do Vercel redirects handle query parameters?

Definition: Query parameters are values in the part of a URL after ?, such as ref=test. As of 17 October 2026, Vercel documents configuration redirects that forward query parameters to the destination and support query-based conditions through has and missing.

Key facts

• Vercel's redirect documentation states that query parameters pass through unless explicitly replaced in the destination.
• The vercel.json reference defines source as a pathname pattern excluding the query string, and supports query conditions in redirect rules.
• Vercel's Configuration Redirects documentation warns that has works when deployed but does not yet work locally with vercel dev.

What happens to incoming query parameters?

Vercel's redirect guide illustrates forwarding with a hostname-scoped rule that sends requests from your-project.vercel.app to www.example.com while preserving the path. Its verification example expects /about?ref=test to reach https://www.example.com/about?ref=test.

This makes the outgoing destination URL part of redirect testing: checking only /about misses the handling of ref=test. In the guide's permanent redirect example, the response has status 308 and a Location header containing the destination URL and query string. The query therefore remains available at the destination page.

How does a rule match a query parameter?

The redirect object reference separates path matching from conditional matching. The source field matches the incoming pathname. A has condition selects requests with the specified property, while missing selects requests where the specified property is absent.

For a query condition, type is query, key names the parameter, and value controls the accepted value. Omitting value permits any value for that key. The reference also supports value objects: eq checks equality.

The following illustrative configuration adapts those documented fields. In the application's root vercel.json, it redirects /start to /end when the query parameter ref equals test:

{
  "redirects": [
    {
      "source": "/start",
      "has": [
        {
          "type": "query",
          "key": "ref",
          "value": { "eq": "test" }
        }
      ],
      "destination": "/end",
      "permanent": false
    }
  ]
}

Here, permanent: false selects a temporary 307 response. Query forwarding applies separately from the condition that selects the request. The condition checks ref; it does not instruct Vercel to remove that parameter from the destination.

How should query-based redirects be checked?

Vercel's Configuration Redirects documentation places has testing on a deployed application because of the local development limitation. For the illustrative rule, useful requests include /start?ref=test, /start?ref=other, and /start.

The first request matches the stated condition. The others check that the rule remains conditional. Inspecting the response status and Location shows both whether the rule runs and which parameters reach its destination. A request with an additional parameter also checks forwarding alongside query-based selection.

Related terms

• URL parameters
• HTTP redirects
• How do I configure redirects in vercel.json?
• How do I redirect a whole URL section on Vercel?

FAQ

Can I put a query string in the source pattern?

The configuration reference defines the redirect source as a pathname pattern excluding the query string. You can express query requirements with has or missing and type: "query".

How can I redirect when a parameter is absent?

You can use a missing condition with type: "query" and the parameter's key. The same reference defines missing as conditional redirect matching based on absence.

Do bulk redirects preserve query parameters by default?

Vercel's same reference gives bulk redirects a separate preserveQueryParams field, whose default is false. You can set it to true to preserve the query string; bulk redirect source fields ignore query parameters.

Sources

1. Vercel, "Redirects", 18 September 2026
2. Vercel, "Static Configuration with vercel.json", 14 August 2026
3. Vercel, "Configuration Redirects", 11 August 2026

---

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