--- title: "Troubleshooting Build Error: \"Serverless Function has exceeded the unzipped maximum size of 250 MB\"" description: Learn how to troubleshoot builds failing due to exceeding the maximum function size limit on Vercel. url: /kb/guide/troubleshooting-function-250mb-limit canonical_url: "https://vercel.com/kb/guide/troubleshooting-function-250mb-limit" last_updated: 2026-07-01 authors: Justin Vitale related: - /docs/fluid-compute - /docs/functions/limitations - /docs/functions/container-images - /changelog/vercel-functions-can-now-be-up-to-5-gb-in-package-size - /docs/environment-variables install_vercel_plugin: npx plugins add vercel/vercel-plugin --- 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. ## Why functions fail when exceeding 250 MB 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](https://vercel.com/docs/fluid-compute). See [large Functions](https://vercel.com/docs/functions/limitations#large-functions-beta) 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](https://vercel.com/docs/functions/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. ## How to identify functions that are exceeding the limit 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` ## Contributing factors to large function sizes - _**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. ## Optimizing and reducing function size ### 1\. Use `includeFiles`/`excludeFiles` in `vercel.json` Not supported in Next.js. Instead, use [\`outputFileTracingIncludes\`](https://nextjs.org/docs/app/api-reference/next-config-js/output) 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`. ### 2\. Bundle your code and enable tree-shaking 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. ### 3\. Remove unused dependencies or use lighter alternatives 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. ### 4\. Offload static assets and heavy processes 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. ## Next steps 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](https://vercel.com/docs/functions/limitations): reference for size, duration, and memory limits, including large Functions. - [Fluid Compute](https://vercel.com/docs/fluid-compute): required for large Functions. - [Container images](https://vercel.com/docs/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](https://vercel.com/changelog/vercel-functions-can-now-be-up-to-5-gb-in-package-size): changelog with background and details. - [Managing environment variables](https://vercel.com/docs/environment-variables): for setting `VERCEL_SUPPORT_LARGE_FUNCTIONS=1` on existing projects. - [Next.js \`outputFileTracing\`](https://nextjs.org/docs/app/api-reference/config/next-config-js/output): control what gets bundled into Next.js functions.