Platform Version Detection
Vercel CLI will automatically upgrade your deployment to the latest platform version if you import a project or if your project meets certain criteria. In order for this to work, you must:
- Remove any Dockerfile.
- Remove the
type
property from yourvercel.json
file. - Remove the
start
script from yourpackage.json
file. - Remove the
server.js
file from the root of your project.
It is possible to opt out of this behavior by creating a vercel.json
file with a version
property.
If you are yet to upgrade to the latest platform version, please read our upgrade guide.
What can I deploy with Vercel?
Vercel is best at deploying technologies that can be served over HTTP and distributed through our CDN network:- Static websites and static generators (Next.js, React, Vue, Angular, etc)
- Code that renders HTML on the server-side
- API endpoints that query databases or web APIs and return dynamic data
In general, most popular technologies and languages already have quickstarts or guides you can start taking advantage of today.
Missing Public Directory
The build step will result in an error if the output directory is missing, empty, or invalid (if it’s actually not a directory). To resolve this error, you can try the following steps:
- Make sure that the output directory is specified correctly in project settings. Here’s the documentation.
- If the output directory is correct, double check the Build Command (documentation) or the root directory (documentation).
- Try running the Build Command locally and make sure that the files are correctly generated in the specified output directory.
Missing Build Script
If your project contains a package.json
file, no api
directory, and no vercel.json
configuration, it is expected to provide a build
script that performs a static build of your frontend and outputs it to a public
directory at the root of your project.
When properly configured, your package.json
file would look similar to this:
{ "scripts": { "build": "[my-framework] build --output public" } }
Once you have defined the build
script, this error will disappear. Furthermore, it will not be displayed if you are using package.json
purely to provide dependencies for your Serverless Functions located inside the api
directory.
Preview Deployment Suffix
The Preview Deployment Suffix feature (available optionally on the "General" team settings page) allows for replacing the vercel.app
suffix of every freshly created deployment with a custom domain of your choice.
In order for this feature to function properly, the custom domain you configured must be:
- Active (not deleted)
- Available within the team that enabled the Preview Deployment Suffix
- Backed by an active wildcard certificate
The easiest way to satisfy all of these constraints is to ensure the domain is also added to a project located within the same team. This project would ideally contain a single index.html
that would display when someone visits the bare domain.
Maximum Team Member Requests
No more than 10 requests of users wanting to join a team can be open at the same time. In order to allow for more requests, the existing ones have to be approved or declined by an owner of the team.
This ensures the list always remains managable and protected against spam.
Inviting Users to Team Who Requested Access
If a user already requested access to a team, it's not possible to invite them. Instead, their request must be approved by an owner of the team in order for the user to gain acess.
This ensures no requests are accidentally accepted.
Blocked Scopes
A Personal Account or Team on Vercel might be blocked if it violates our Fair Use Policy or Terms of Service.
Blocked Personal Accounts or Teams cannot create new Deployments, or be invited to new Teams. Please contact Vercel Support if you need help.
Unused Build & Development Settings
A Project has several settings that can be found in the dashboard. One of those sections, "Build & Development Settings", is used to change the way a Project is built.
However, the Build & Development Settings are only applied to zero-configuration Deployments.
If a Deployment defines the builds
configuration property, the Build & Development Settings are ignored.
Unused Serverless Function Region Setting
A Project has several settings that can be found in the dashboard. One of those settings, "Serverless Function Region", is used to select the region where your Serverless Functions execute.
If a Deployment defines the regions
configuration property, the "Serverless Function Region" setting is ignored.
If a CLI Deployment defines the --regions
option, the "Serverless Function Region" setting is ignored.
Invalid Route Source Pattern
The source
property follows the syntax from path-to-regexp, not the RegExp
syntax.
For example, negative lookaheads must be wrapped in a group.
Before
{ "source": "/feedback/(?!general)", "destination": "/api/feedback/general" }
After
{ "source": "/feedback/((?!general).*)", "destination": "/api/feedback/general" }
Invalid Route Destination Segment
The source
property follows the syntax from path-to-regexp.
This means that a colon (:
) defines the start of a named segment parameter.
A named segment parameter defined in the destination
property must also be defined in the source
property.
Before
{ "source": "/feedback/:type", "destination": "/api/feedback/:id" }
After
{ "source": "/feedback/:id", "destination": "/api/feedback/:id" }
Failed to Install Dependencies in Development
When running the vercel dev
command, you may experience an npm install
error. This happens when npm
is invoked to install Runtimes that are defined in your vercel.json
file.
npm install
may fail if:
npm
is not installed (retrieve it from here)- Your internet connection is unavailable
- The Runtime that is defined in your configuration is not published to the npm registry
Please double-check that the name and version of the Runtime you are requesting is correct.
Mixed Routing Properties
If you have rewrites
, redirects
, headers
, cleanUrls
or trailingSlash
defined in your configuration file, then routes
cannot be defined.
This is a necessary limitation because routes
is a lower-level primitive that contains all of the other types. Therefore, it cannot be merged safely with the new properties.
See the Advanced Routing section for examples of routes
compared to the new properties.
Conflicting Configuration Files
For backwards compatability purposes, there are two naming conventions for configuration files used by Vercel CLI (for example vercel.json
and now.json
). Both naming conventions are supported, however only one may be defined at a time. The CLI will output an error message if both naming conventions are used at the same time.
These conflicting configuration errors occur if:
- Both
vercel.json
andnow.json
exist in your project.
Solution: Delete thenow.json
file. - Both
.vercel
and.now
directories exist in your project.
Solution: Delete the.now
directory. - Both
.vercelignore
and.nowignore
files exist in your project.
Solution: Delete the.nowignore
file. - Environment Variables that begin with
VERCEL_
have a conflicting Environment Variable that begins withNOW_
.
Solution: Only define theVERCEL_
prefixed Environment Variable.
Conflicting "functions" and "builds" Configuration
There are two different ways to configure Serverless Functions in your project: functions
or builds
. However, only one of them may be used at a time - they cannot be used in conjuction.
For most cases, it is recommended to use the functions
property because it supports more features, such as:
- Allows configuration of the amount of memory that the Serverless Function is provided with.
- More reliable because it requires a specific npm package version for the
runtime
property. - Supports "clean URLs" by default, which means that the Serverless Functions are automatically accessible without their file extension in the URL.
However, the builds
property will remain supported for backwards compatibility purposes.
Unsupported Functions Configuration with Next.js
When using Next.js, only memory
and maxDuration
can be configured within the functions property. Next.js automatically handles the other configuration values for you.
Deploying Serverless Functions to Multiple Regions
It's possible to deploy Serverless Functions to multiple regions, but it's restricted to the Enterprise plan for Teams.
On the Pro plan, the limitation has been around since the launch of the current pricing model but was applied on July 10, 2020. For Projects created on or after the date, it's no longer possible to deploy to multiple regions.
To select a single suitable region for your Serverless Functions, please read our guide.
Unmatched Function Pattern
The functions
property uses a glob pattern for each key. This pattern must match Serverless Function source files within the api
directory.
If you are using Next.js, Serverless Functions source files can be created in the following:
pages/api
directorysrc/pages/api
directorypages
directory when the module exports getServerSidePropssrc/pages
directory when the module exports getServerSideProps
Additionally, if you'd like to use a Serverless Function that isn't written with Node.js in combination with Next.js, you can place it in the api
directory (provided by the platform), since pages/api
(provided by Next.js) only supports JavaScript.
Not Allowed
{ "functions": { "users/**/*.js": { "maxDuration": 30 } } }
Allowed
{ "functions": { "api/users/**/*.js": { "maxDuration": 30 } } }
Allowed (Next.js)
{ "functions": { "pages/api/users/**/*.js": { "maxDuration": 30 } } }
Cannot Load Project Settings
If the Project configuration in .vercel
belongs to a Team you are not a member of, attempting to deploy the Project will result in an error.
This may happen if you clone a Git repository that includes the .vercel
directory, or you are logged in to the wrong Vercel Account.
To fix it, remove the .vercel
directory and deploy to link the Project again by running these commands.
On macOS and Linux:
rm -rf .vercel
vercel
On Windows:
rmdir /s /q .vercel
vercel
Project Name Validation
Project names can only consist of up to 100 alphanumeric lowercase characters. Hyphens can be used in between the name, but never at the start or end.
Repository Connection Limitation
The amount of Vercel Projects that can be connected with the same Git repository is limited depending on your plan.
If you have reached the limitation and would like to connect a new Project to the repository, you will need to disconnect an existing Project from the same Git repository.
To increase this limit, please contact our Sales Team.
Bypassing Password Protection Programmatically
When Password Protection is enabled on your Project, you can bypass the protection programmatically with the following steps:
- Send a
POST
request to your Deployment with the password in the request body (_vercel_password=<password>
). - Parse the
Set-Cookie
response header and extract the cookie_vercel_jwt
from the response. - Set the cookie to the
Cookie
request header when you access the Deployment.
Example Request
cookie="$(curl -s -D - -o /dev/null -X POST -d "_vercel_password=<password>" https://example.vercel.app | grep -i Set-Cookie | grep _vercel_jwt | awk {'print $2'})" curl -H "Cookie: $cookie" https://example.vercel.app
These steps are required for every URL and cookie values cannot be shared across Deployments.
Domain Verification via CLI
It is no longer necessary to verify your ownership of a Domain using the vercel domains verify
command provided by Vercel CLI.
Instead, it's now only necessary for you to point the Domain to Vercel by configuring our nameservers or a DNS Record. You can learn more about what to do exactly for your Domain by running vercel domains inspect <domain>
, where <domain>
is the Domain you're interested in.
Alternatively, if you already added it to a Project, read this section.
Leaving The Team
You can't leave a team if you are the last remaining owner or the last confirmed member. In order to leave it, you first have to designate a different confirmed member to be an owner of the team.
If you are the only remaining member, you should delete the team instead.
Git Default Ignore List
Deployments created using Vercel CLI will automatically ignore several files for security and performance reasons.
However, these files are not ignored for deployments created using Git and a warning is printed instead. This is because .gitignore
determines which files should be ignored.
If the file was intentionally committed to Git, you can ignore the warning.
If the file was accidentally committed to Git, you can remove it using the following commands:
git rm file.txt # remove the file echo 'file.txt' >> .gitignore # append file to .gitignore git add .gitignore # stage the change git commit -m "Removed file.txt" # commit the change git push # deploy the change
GitHub App Installation Not Found
In some cases, signing up with GitHub fails due to GitHub's database inconsistencies.
When you connected your Personal Vercel Account with your GitHub account, the Vercel GitHub App was installed on your GitHub account and then GitHub notified Vercel that the app was successfully installed.
However, Vercel was unable to retrieve the app installation from GitHub, which made it appear as if the Vercel GitHub App was never installed.
In order to solve this issue, please wait a minute and try connecting to GitHub again. If you are still unable to connect, please contact GitHub Support to determine why the Vercel GitHub App was not able to be installed.
Lost Git Repository Access
In order for Vercel to be able to deploy commits to your Git repository, a Project on Vercel has to be connected to it.
This connection is interrupted if the Git repository is deleted, archived, or if the Vercel App was uninstalled from the corresponding Git account or Git organization. Make sure none of these things apply.
Additionally, when using GitHub, the connection is also interrupted if you or a member of your team modifies the access permissions of the Vercel GitHub App installed on the respective personal GitHub account or GitHub organization.
To verify the access permissions of the Vercel GitHub App installed on your personal GitHub account, navigate to the "Applications" page and select "Vercel" under "Installed GitHub Apps". You will see a list of Git repositories that the GitHub App has access to. Make sure that the Git repository you're looking to connect to a Vercel Project is listed there.
To verify the access permissions of the Vercel GitHub App installed on your GitHub organization, select "Vercel" under "Installed GitHub Apps" in the organization settings. You will see a list of Git repositories that the GitHub App has access to. Make sure that the Git repository you're looking to connect to a Vercel Project is listed there.
Setting Production Branch as Preview
You can only assign non-Production branches to your project's Preview domains. The Production branch must be assigned to a Production environment domain.
Production Deployment cannot be redeployed
You cannot redeploy a Production Deployment if a more recent one exists.
The reason is that redeploying an old Production Deployment would result in overwriting the most recent source code you have deployed to Production.
To force an explicit overwrite of the current Production Deployment, click "Promote to Production" instead.
Non Git Deployment Cannot Be Redeployed from Dashboard
You cannot redeploy a Deployment from the Dashboard if it hasn't been created via Git.
To redeploy a Deployment that was created via Vercel CLI, run vercel
within the directory in which the original Deployment was created.
Non Git Deployment Cannot Be Promoted to Production from Dashboard
You cannot promote a Deployment to Production from the Dashboard if it wasn't created via Git.
To promote a Deployment to Production that was created via Vercel CLI, run vercel --prod
within the directory in which the original Deployment was created.
SSL Certificate Deletion Denied
Certain SSL Certificates associated with your Personal Account or Team (i.e. Wildcard SSL Certificates for your Vercel Project's staging Domains) are automatically generated by the Vercel platform.
Because these SSL Certificates are managed by the Vercel platform, they cannot be manually deleted on the Vercel Dashboard – nor via Vercel CLI.
Custom SSL Certificates may be uploaded to Teams on the Enteprise plan, which are allowed to be manually deleted.