Why does my Serverless Function work locally but not when deployed?

It can be frustrating when your code works locally, but not when deployed to production. There are a few nuances with Serverless Functions that may cause them to work in your local environment, but not when deployed. Read on to learn how to troubleshoot such a situation.

Native Dependencies

One of the common reasons for different behavior across environments is whether or not your Serverless Functions depend on packages with native dependencies. Native in this context refers to software that needs to be compiled and integrated with JavaScript through a layer like node-gyp.

A great example of such a package is the bcrypt library which is a popular choice for encrypting passwords. You might be able to install bcrypt without issues on your local machine, but there is no guarantee that those native packages are available in the Serverless Function environment.

You should look for alternative packages that achieve similar results without native dependencies for a consistent experience. bcryptjs is an example of a pure JavaScript implementation that works across different environments without any native dependencies.

Note: You may be able to install the necessary shared libraries in the Build Image prior to running npm install

Reading From or Writing To the Filesystem

On your local machine, you have access to a persistent filesystem that you can read from and write to. This is not the case for Serverless Functions. Serverless Functions are stateless and cannot be depended on as a storage solution.

While Serverless Functions have a writeable /tmp scratch space up to 500 MB, it is not recommended to use this approach. Also, Edge Functions do not have filesystem access due to their ephemeral nature.

The proper approach is to leverage an external storage solution that you can query from your development, preview, and production environments through a consistent interface.

Depending on your requirements, you may wish to use a Content Management System (CMS) or Database to store data that can be read and updated by your app. You can read more about using both options with Vercel and the correct approaches to take when doing so in the documentation:

Environment Variables

If you have any environment variables defined in your local environment that your Serverless Functions depend on, you'll need to make sure they are defined the same way in your Preview, and Production environments. The Environment Variables UI provides an easy way to do so.


Logging is essential to debugging your software. Place log statements in key areas of your code to better understand what's going on. Make sure to install a Log Drain Integration for your deployed functions so you can have persistent debugging information available when needed. Consult your logs to see if there are any differences across environments.

Community Support

If you're still stuck after considering all of the above and need a fresh pair of eyes on your problem, consider starting a Discussion to get help from our GitHub community. When starting discussions requesting help, please provide detailed steps on how to reproduce the issue you're running into along with the solutions you've tried so far.

Couldn't find the guide you need?