Troubleshooting Next.js on Netlify

Legacy Next.js Runtime

The information on this page applies to Next.js version 10-13.4 and Netlify Next.js Runtime v4, which is currently in maintenance support.

Visit our Next.js adapter docs for info on newer versions of Next.js.

If you encounter issues running Next.js on Netlify, the information on this page may help you solve them.

Including content files for SSR/ISR

If your server-rendered page relies on local files in your repository, the files need to be bundled with the handler functions. This can be done by modifying your file based configuration.

Under the functions option, add an entry to the included_files option. Be careful to not include unnecessary files. Particularly large files like images or videos can make your handler function sizes grow quickly. There is a 250 MB size limit for each handler’s unzipped function bundle.

Review the Functions Configuration Docs for more information.

Update your netlify.toml file to include the following (assuming local content is located in the /content directory):

[functions]
  included_files = ["content/**"]

Large function error

You may encounter an error about generated functions being too large. During deployment, each unzipped function bundle is limited to 250 MB in size. The cause of this error could be large dependencies or a large number of pre-rendered pages. The list of largest files shown in the build logs will help you determine the cause.

Large dependencies

This is the most common root cause of generated functions being too large. Some node modules are very large, mostly those that include native modules. Examples include electron and chromium.

The function bundler is usually able to find modules that are actually used by your code, but sometimes it will incorrectly include unneeded modules. If this is the case, you can either remove the module from your dependencies if you installed it yourself, or exclude it manually in your netlify.toml.

[functions]
  included_files = ["!node_modules/A_LARGE_MODULE/**/*"]

In the above example, you should change the value to match the problematic module. The ! at the beginning of the module path indicates that it should be excluded.

If you do need large modules at runtime, you can try changing to a Netlify Function which has less overhead than the equivalent Next.js function.

Large numbers of pre-rendered pages

A large number of pre-rendered pages can take up a lot of space in the function. To fix this, consider deferring the building of the pages. If you return fallback: "blocking" from getStaticPaths, the rendering will be deferred until the first user requests the page. This approach reduces build and deploy time, and can make your bundle a lot smaller.

Netlify Support Forums

Can’t find what you’re looking for? The Netlify Support Forums are a great place to find more information and ask questions that are specific to your needs.