Vercel fails with a function larger than the 250 MB uncompressed limit
The Vercel Function "api/hello" is 300mb uncompressed which exceeds the maximum uncompressed size limit of 250mb.Short answer
A Node.js Vercel Function may not be larger than 250 MB uncompressed. Turn on the build analyzer to see the biggest files, then remove them: exclude files you do not need, dedupe packages, move assets out of server code, or switch to large functions if you truly need the size.
Fix it fast
1Find out which cause you have
Add the environment variable VERCEL_ANALYZE_BUILD_OUTPUT with the value 1, redeploy, and read the build log. It lists each function's size and its largest files.
npx vercel env add VERCEL_ANALYZE_BUILD_OUTPUT production # enter the value 1, then redeploy npx vercel --prod2Match what you see, then jump to its fix
- 1
Large dependencies in the analyzer output name a package such as a bundled browser or a machine learning libraryA heavy dependency, or the same package installed twiceFix - 2
Test folders, images or other static files appear in the analyzer listFiles are traced into the function that it does not needFix - 3
A directory you never import by name shows up in the analyzer outputAn import path built at runtime pulls in a whole folderFix - 4
The analyzer shows only needed files and the total is still over the limitThe function really needs more than 250 MBFix
- 1
What does the error look like?
The Vercel Function "api/hello" is 300mb uncompressed which exceeds the maximum uncompressed size limit of 250mb.Serverless Function exceeded 250 MB
Cause 1 of 4
A heavy dependency, or the same package installed twice
1Check
Packages that ship binaries add a lot of size, and duplicate copies add more. See why a package is installed.
npm ls <package-name>2Fix
Remove duplicates, drop packages you do not call from the function, or switch to a lighter alternative.
npm dedupe3Verify
Redeploy and check that the size in the analyzer output went down.
npx vercel --prodConfirmed by vercel.com
Cause 2 of 4
Files are traced into the function that it does not need
1Check
Images, videos or large JSON files that server code imports or reads end up in the function bundle.
du -sh public test data 2>/dev/null2Fix
Exclude them in vercel.json. For Next.js use outputFileTracingExcludes in next.config.js, because excludeFiles is not supported there.
{
"functions": {
"api/**": {
"excludeFiles": "{public,test}/**"
}
}
}3Verify
Redeploy and compare the function size in the log.
npx vercel --prodConfirmed by vercel.com
Cause 3 of 4
An import path built at runtime pulls in a whole folder
1Check
A dynamic import or require with a variable path can make the bundler include the whole directory it might point to.
grep -rn "require(\|import(" api src | grep -v "'"2Fix
Use static import paths where you can, and serve large images, videos and JSON from the public directory or external storage.
// instead of: require(`./data/${name}.json`)
import users from './data/users.json';3Verify
Redeploy and check the function size again.
npx vercel --prodConfirmed by vercel.com
Cause 4 of 4
The function really needs more than 250 MB
1Check
Large functions (beta) allow up to 5 GB. They need Fluid compute with Active CPU enabled and a Node.js, Bun or Python runtime.
npx vercel env ls2Fix
Set the project environment variable VERCEL_SUPPORT_LARGE_FUNCTIONS to 1. Set it to 0 to switch it off again.
npx vercel env add VERCEL_SUPPORT_LARGE_FUNCTIONS production
# enter the value 13Verify
Redeploy. The build no longer fails on size.
npx vercel --prodConfirmed by vercel.com
How do I stop it coming back?
- Keep the analyzer variable on in preview deployments so size growth shows early.
- Put images, videos and big JSON in public or in object storage, not in server imports.
- Run npm dedupe after large dependency upgrades.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix