Frequently Asked Questions

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 your vercel.json file.
• Remove the start script from your package.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.

Green Energy Policy

The Serverless approach is an energy-efficient alternative to traditional servers because your code runs only on-demand.

For more information on our cloud partners' Green energy policies, we recommend viewing their documentation:

• AWS Sustainability Timeline
• Google Cloud Sustainability
• Microsoft Environmental Sustainability

What can I deploy with Vercel?

• 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"
  }
}

An example build script in a package.json file that specifies the output directory.

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.

Broken 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.

Unused Build & Development Settings

A Project has several settings that can be found in the dashboard. One of those sections is called "Build & Development Settings" and 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.

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 and now.json exist in your project.
  Solution: Delete the now.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 with NOW_.
  Solution: Only define the VERCEL_ 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 used to configure functions. Next.js 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 directory
• src/pages/api directory
• pages directory when the module exports getServerSideProps
• src/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

A Git Repository cannot be connected to more than 20 Projects on Vercel (not including deleted Projects) so that Pull Requests will have a reasonable number of comments and deployments.

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 repository.

If you would like to increase this limit, please contact Vercel Support.

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 in Vercel CLI anymore.

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.