Troubleshooting Build Error: "Serverless Function has exceeded the unzipped maximum size of 250 MB"

When a deployment fails with Serverless Function has exceeded the unzipped maximum size of 250 MB, the packaged function bundle, including your code and its dependencies, is larger than the standard size limit for a Vercel Function. This guide explains why the error occurs, how to identify which functions are too large, and how to resolve it by opting into large Functions or reducing the bundle.

For Vercel Functions, the standard maximum uncompressed size is 250 MB (approximately 50 MB compressed, or 500 MB uncompressed for Python). After Vercel builds your application and packages the function, the unzipped bundle must stay within this limit on the standard path.

If your function needs to be larger than 250 MB, Vercel supports bundles up to 5 GB uncompressed on Fluid Compute. See large Functions for full details. Key points:

• Fluid Compute required (with Active CPU enabled). Fluid Compute is on by default for new projects.
• Supported runtimes: Node.js, Python, and container images built from a Dockerfile or Containerfile.
• New projects (created after June 30, 2026) are automatically enrolled.
• Existing projects opt in by setting the VERCEL_SUPPORT_LARGE_FUNCTIONS=1 environment variable and redeploying. A project created before June 30, 2026 that hits this error only needs to opt in.

If your project qualifies, enabling large Functions can resolve the error without further changes. It's worth investigating what's driving the bundle size; the sections below walk through identification and optimization.

Add the VERCEL_ANALYZE_BUILD_OUTPUT=1 environment variable and redeploy. Build logs will show uncompressed function sizes in MB, with a breakdown of the largest contributors:

Function : /api
Size     : 1991.54 MB
  Large dependencies:
    • _vendor/tensorflow/libtensorflow_cc.so.2: 972.15 MB
    • _vendor/tensorflow/include: 307.87 MB
    • _vendor/tensorflow/libtensorflow_framework.so.2: 241.81 MB
    • _vendor/tensorflow/python: 134.73 MB

For Next.js projects, you can also set VERCEL_BUILDER_DEBUG=1. The build logs will then include function sizes in bytes:

      "pages": [
        "api/dates.js"
      ],
      ...
      "uncompressedLayerBytes": 273655603
    }
...
Serverless Function's page: api/dates.js
Large Dependencies                         Uncompressed size
storage/sample-a                                    54.46 MB
storage/sample-b                                    17.79 MB

• Large dependencies or bloated node_modules: The most common cause is a heavy dependency tree. Duplicate sub-dependencies can also inflate size. A frequent example is Puppeteer, which ships a full headless Chrome browser (exactly the kind of workload large Functions are designed to support). On an existing project, set VERCEL_SUPPORT_LARGE_FUNCTIONS=1 to opt in; the optimization steps below can bring the bundle down if you'd rather keep it small.
• Static assets bundled into functions: Large static files (images, videos, JSON data) should be served via a CDN, not included in your function bundle. If server-side code imports these assets, they get packaged with the function.
• Excessive server-side logic or framework overhead: Server-side rendering that pulls in large runtime code or entire UI libraries can inflate a bundle. Dynamic imports or requires with variable paths can also confuse bundlers into including everything in a directory.

Not supported in Next.js. Instead, use `outputFileTracingIncludes` in next.config.js.

Vercel lets you explicitly include or exclude files from your functions via vercel.json. If a function does not need certain directories, exclude them so they are not uploaded:

{
  "functions": {
    "api/**": {
      "excludeFiles": "{.next,*.cache,node_modules,public,app}/**"
    }
  }
}

For Next.js projects, use outputFileTracing in next.config.js. The Next.js runtime does not read excludeFiles from vercel.json.

Next.js, SvelteKit, and Nuxt handle tree-shaking automatically (Next.js via webpack/Turbopack, SvelteKit and Nuxt via Vite/Rollup or Vite/webpack). If you are using a framework or setup that does not bundle automatically, use a bundler (Webpack, Rollup, or esbuild) to produce an optimized output rather than deploying raw node_modules and source files. Tree-shaking removes unused code, so only the parts of libraries you use end up in the bundle.

Keep import statements static so the bundler can determine what is needed. A fully dynamic import of an unknown path will cause the bundler to include an entire directory by default.

Audit dependencies and remove anything not used in production. Bundle analyzers can identify large packages. Run npm dedupe (or yarn dedupe) to remove duplicate packages, and use npm ls or yarn why to trace why a large library is being pulled in.

Treat static files (images, PDFs, videos, large JSON) as static assets, not as part of your function code. Store them in the public/ directory (served over the CDN) or an external store, and import only the code your function needs at runtime.

Hitting function size limits is usually a signal to optimize your application or reconsider your architecture. Work through the identification and optimization steps above first: a smaller bundle means faster cold starts and a cleaner project overall. If your workload requires more than 250 MB, opt into large Functions and redeploy.

• Vercel Functions limitations: reference for size, duration, and memory limits, including large Functions.
• Fluid Compute: required for large Functions.
• Container images: deploy HTTP servers from a Dockerfile or Containerfile as a Vercel Function.
• Vercel Functions can now be up to 5 GB in package size: changelog with background and details.
• Managing environment variables: for setting VERCEL_SUPPORT_LARGE_FUNCTIONS=1 on existing projects.
• Next.js `outputFileTracing`: control what gets bundled into Next.js functions.