When Vercel receives a request, it goes through a chain of actions to resolve that request to the right destination including DNS, resolving to a project, and running the routes for a specific deployment. While processing the request, there are many features that can affect the final destination, and routing rules can change the path, redirect, or even rewrite to another destination. This guide will walk through how to debug what is happening when Vercel is making these decisions.
For an introduction to Vercel's routing, read the Life of a Vercel request blog post.
Vercel offers the ability to purchase and manage domains on the Vercel platform, including setting DNS records and using Vercel nameservers. See Domains documentation for more information.
The first thing that Vercel must do when receiving a request is resolve the DNS settings for the domain. To check that the domain is working, follow the domains troubleshooting documentation. Make sure to check for issues such as correctly configured nameservers, DNS records, and that the domain is assigned to a project.
Vercel can be used to manage domains without connecting to a Vercel project. However, if a domain is connected to a project, Vercel must then decide what project to route the request to.
Custom domains must be connected to a Vercel project through the Domains tab in Settings. Once connected, when Vercel receives a request for that domain, it will be automatically routed to the deployment for that project (see more about this below).
Vercel Observability and Logs can be used to make sure that the correct project is receiving a request. After visiting the URL, check to make sure that there is a record of that request. The name of the project should be shown for the request. It may take a few minutes for the request to appear.
Vercel also generates domain aliases for deployments, such as a unique alias for deployments on the same git branch or a unique URL for each deployment. These domain aliases do not need to be configured in settings, but otherwise behave similar to configured production domains. See Generated URLs documentation for more information.
Vercel can route requests on the same domain to multiple projects with microfrontends. When Vercel receives a request to a microfrontends group, it loads the microfrontends.json file for the default app deployment. Based on the configured path expressions, Vercel's CDN will route the request to the appropriate project. This logic runs early in the lifecycle of a request. After microfrontends runs, the request is handled afterwards as if it was a normal request to the target project.
Vercel supports session tracing which can be used to debug this process. To debug a particular request, follow the directions to run a page trace and then open up the resulting trace. The top level span for the trace will contain attributes to identify the project that the request was routed to. Additionally, there is a span for Microfrontends Routing that will contain the information about why the request was routed to a specific project. Look for the vercel.mfe.app and vercel.mfe.matched_path attributes for more information.
Once the correct project has been identified, Vercel must then load information from a specific deployment from that project. For custom domains, Vercel will use the domains settings to decide where to route the request to. For example, if a custom domain is assigned to Production, then the current production deployment will be chosen for requests to that domain. For generated URLs, Vercel follows the rules for that URL. For example, Vercel generates a URL for every git branch that a deployment is created on. When a user visits the generated URL, they will always be routed to the latest deployment on that branch.
Some Vercel features, such as Skew Protection and Rolling Releases, may change the chosen deployment ID. With Skew Protection, when a request is received with the skew protection identifier, Vercel may choose to route the request to the specified deployment to avoid version skew. Certain requirements must be true, such as the deployment ID being part of the same project and within the skew protection window. When Rolling Releases are active, a user may be route to one of two deployments depending on the release progress. A portion of users are routed to the new deployment to be able to test it before rolling it out 100%. After the release is finished, all users will be routed to the current production deployment again.
The specific deployment ID that a request was routed to can be seen in the traces discussed above. The deployment ID will also be visible in Logs.
Finally, when the deployment is chosen, Vercel's loads the routes for that deployment and executes them in order. Routes can be specified in multiple ways, such as with vercel.json, in a framework configuration such as next.config.js, or automatically through Framework Defined Infrastructure. The Vercel Firewall also runs on requests to make sure they are protected.
Logs is a good first tool to use when debugging a request. An entry in Logs is generated for each request and it contains a lot of information about what happened during that request. For example, you can see whether the firewall allowed the request, whether middleware was run, or which function was executed. Logs will also show the deployment ID that the request was routed to, and whether features such as Rolling Releases affected the request.
Traces can also provide a lot of information. You can run a page trace for the request and then in the resulting trace, you can find information such as the project ID, deployment ID, microfrontends routing, and what happened during the request. If using external rewrites, you will also see the destination of the rewrite and how long the destination took to handle the request.
The Vercel dashboard also provides information about the routes for a deployment. On a deployment page, open the Deployment Summary accordion to view deployed resources such as middleware paths, functions, ISR pages, and static assets. This information can also be seen in the Resources tab for a deployment where you can search for specific resources.