[cli] Throw explicit error when vercel.ts `routes` conversion creates a conflict by MatthewStanciu · Pull Request #14709 · vercel/vercel

MatthewStanciu · 2026-01-23T01:01:40Z

#14705 fixes this use case of vercel.ts:

// ✅ fixed
export const config: VercelConfig = {
  routes: [
    routes.rewrite('/test-header', 'https://httpbin.org/headers', {
      requestHeaders: {
        authorization: `Bearer token`,
      },
    }),
    routes.redirect('/test-build', 'https://httpbin.org/headers'),
  ]
};

But the user can still have a confusing experience if they do this:

// ❌ not fixed
export const config: VercelConfig = {
  rewrites: [
    routes.rewrite('/test-env', 'https://httpbin.org/headers', {
      requestHeaders: {
        authorization: `Bearer ${deploymentEnv('API_TOKEN')}`,
      },
    }),
    routes.rewrite('/test-rewrite-regular', 'https://httpbin.org/headers')
  ],
  redirects: [
    routes.redirect('/test-build', 'https://httpbin.org/headers'),
  ]
};

This will fail with the error message:

Error: If `rewrites`, `redirects`, `headers`, `cleanUrls` or `trailingSlash` are used, then `routes` cannot be present.

But that's not clear because from the user's perspective they separated their rewrites and redirects like the docs say, so where is routes coming from?

We're not going to compile the redirects to routes (#14679), so we need the error message to be clearer.

This PR fails the build during config compilation if after normalization (AKA compiling anything to routes that needs this transformation) there's still a conflict. In this case, since it has the full context of what just happened (unlike the generic vercel.json error it currently throws) it can throw a more descriptive error message with clear instructions for what to do.

changeset-bot · 2026-01-23T01:01:46Z

🦋 Changeset detected

Latest commit: 05c3d1d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
vercel	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-01-23T01:02:22Z

📦 CLI Tarball Ready

The Vercel CLI tarball for this PR is now available!

Quick Test

You can test this PR's CLI directly by running:

npx https://vercel-or2ad969i.vercel.sh/tarballs/vercel.tgz --help

Use in vercel.json

To use this CLI version in your project builds, add to your vercel.json:

{
  "build": {
    "env": {
      "VERCEL_CLI_VERSION": "vercel@https://vercel-or2ad969i.vercel.sh/tarballs/vercel.tgz"
    }
  }
}

github-actions · 2026-01-23T01:04:22Z

🧪 Unit Test Strategy

Comparing: db9ec7c → 05c3d1d (view diff)

Strategy: Affected packages only

✅ Only testing packages that have been modified or depend on modified packages.

Affected packages - 1 (2%)

vercel

Unaffected packages - 40 (98%)

@vercel-internals/get-package-json
@vercel/backends
@vercel/build-utils
@vercel/cervel
@vercel/cli-auth
@vercel/client
@vercel/config
@vercel/detect-agent
@vercel/edge
@vercel/elysia
@vercel/error-utils
@vercel/express
@vercel/fastify
@vercel/firewall
@vercel/frameworks
@vercel/fs-detectors
@vercel/functions
@vercel/gatsby-plugin-vercel-builder
@vercel/go
@vercel/h3
@vercel/hono
@vercel/hydrogen
@vercel/introspection
@vercel/koa
@vercel/nestjs
@vercel/next
@vercel/node
@vercel/oidc
@vercel/oidc-aws-credentials-provider
@vercel/python
@vercel/python-analysis
@vercel/redwood
@vercel/related-projects
@vercel/remix-builder
@vercel/routing-utils
@vercel/ruby
@vercel/rust
@vercel/static-build
@vercel/static-config
examples

Results

Unit tests: Only affected packages will run unit tests
E2E tests: Handled separately (Version Packages PRs or run-e2e-tests label)
Type checks: Only affected packages will run type checks

This comment is automatically generated based on the affected testing strategy

packages/cli/src/util/compile-vercel-config.ts

…config' into matthew/explicit-error

vercel

Additional Suggestion:

toRouteFormat is called with 2 parameters but only accepts 1, and undefined isRouteFormat function is called

…config' into matthew/explicit-error

vercel

Additional Suggestion:

Test 'should produce invalid config when rewrites have transforms but redirects do not' expects no error but normalizeConfig throws when arrays have conflicting conversion requirements

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## vercel@50.5.1 ### Patch Changes - Mild refactor of compile-vercel-config ([#14707](#14707)) - Throw explicit error when vercel.ts routes compilation creates a conflict ([#14709](#14709)) - vercel.ts: normalize items in `routes` array to routes format ([#14705](#14705)) - Improvements to vercel api command. Better ls, and help output ([#14720](#14720)) - Updated dependencies \[[`e0e7e3cdd180eb1e07e2ebaba809a2486b546b5d`](e0e7e3c)]: - @vercel/rust@1.0.5 ## @vercel/config@0.0.27 ### Patch Changes - Remove references to nonexistent `redirects` property ([#14708](#14708)) ## @vercel/rust@1.0.5 ### Patch Changes - Do not allow production prebuilt deployments on Windows ([#14724](#14724)) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

MatthewStanciu added 9 commits January 22, 2026 14:42

Normalize items in the routes array to the routes syntax

81c62af

changeset

5af5e48

add test

1b14ea5

statusCode is not unique

7cc80d0

fix test name

17e60a8

Mild refactor compile-vercel-config

f325a78

proper types

0c3281c

changeset

4d78897

Throw explicit error when routes conversion generates a conflict

1132b77

MatthewStanciu changed the base branch from main to matthew/refactor-compile-vercel-config January 23, 2026 01:02

vercel bot deployed to Preview January 23, 2026 01:02 View deployment

changeset

e0e416b

vercel bot deployed to Preview January 23, 2026 01:03 View deployment

MatthewStanciu marked this pull request as ready for review January 23, 2026 01:08

MatthewStanciu requested a review from a team as a code owner January 23, 2026 01:08

MatthewStanciu requested a review from mknichel January 23, 2026 01:09

make better

6a227a8

vercel bot deployed to Preview January 23, 2026 18:43 View deployment

hmm

00ba984

vercel bot deployed to Preview January 23, 2026 19:00 View deployment

vercel bot reviewed Jan 23, 2026

View reviewed changes

packages/cli/src/util/compile-vercel-config.ts Outdated Show resolved Hide resolved

how about this

58770ba

vercel bot deployed to Preview January 23, 2026 22:06 View deployment

mknichel reviewed Jan 23, 2026

View reviewed changes

packages/cli/src/util/compile-vercel-config.ts Outdated Show resolved Hide resolved

MatthewStanciu added 3 commits January 23, 2026 15:49

headers

5beaebd

remove normalizeArrayField

bc5ce93

little thing

7284fd1

MatthewStanciu added 4 commits January 23, 2026 16:02

add tests

4563b87

Merge remote-tracking branch 'origin/matthew/refactor-compile-vercel-…

d153274

…config' into matthew/explicit-error

does this work maybe

17cebd7

reorder

a9a3e70

vercel bot deployed to Preview January 24, 2026 00:41 View deployment

mknichel approved these changes Jan 24, 2026

View reviewed changes

MatthewStanciu added 2 commits January 23, 2026 16:51

Merge branch 'main' into matthew/refactor-compile-vercel-config

14ce6d2

Merge remote-tracking branch 'origin/matthew/refactor-compile-vercel-…

c89558b

…config' into matthew/explicit-error

vercel bot deployed to Preview January 24, 2026 00:53 View deployment

vercel bot reviewed Jan 24, 2026

View reviewed changes

MatthewStanciu added 2 commits January 23, 2026 16:56

fix

edfa0ea

Merge remote-tracking branch 'origin/matthew/refactor-compile-vercel-…

fee3c52

…config' into matthew/explicit-error

vercel bot deployed to Preview January 24, 2026 01:01 View deployment

Base automatically changed from matthew/refactor-compile-vercel-config to main January 24, 2026 01:08

Merge remote-tracking branch 'origin/main' into matthew/explicit-error

16ba99b

vercel bot deployed to Preview January 24, 2026 01:10 View deployment

vercel bot reviewed Jan 24, 2026

View reviewed changes

remove old test again

05c3d1d

vercel bot deployed to Preview January 24, 2026 01:22 View deployment

MatthewStanciu merged commit 7944bdd into main Jan 24, 2026
226 of 228 checks passed

MatthewStanciu deleted the matthew/explicit-error branch January 24, 2026 01:50

vercel-release-bot mentioned this pull request Jan 24, 2026

Version Packages #14721

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[cli] Throw explicit error when vercel.ts `routes` conversion creates a conflict#14709

[cli] Throw explicit error when vercel.ts `routes` conversion creates a conflict#14709
MatthewStanciu merged 26 commits intomainfrom
matthew/explicit-error

MatthewStanciu commented Jan 23, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

vercel bot left a comment

Uh oh!

vercel bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

MatthewStanciu commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 CLI Tarball Ready

Quick Test

Use in vercel.json

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 Unit Test Strategy

Results

Uh oh!

Uh oh!

Uh oh!

vercel bot left a comment

Choose a reason for hiding this comment

Uh oh!

vercel bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MatthewStanciu commented Jan 23, 2026 •

edited

Loading

changeset-bot bot commented Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 23, 2026 •

edited

Loading