Troubleshooting

Start with your server's logs, which show errors from your code and from your server starting and stopping.

Error responses

Your server's responses reach visitors with the status code your server set. When Netlify can't get a response from your server, the visitor receives one of the following instead:

Status	Cause
`429 Too Many Requests`	All of the requests the instance handles at once are in use, and none freed up in time. Refer to Request concurrency.
`500 Internal Server Error`	Your server couldn't start, or a handler or Fetchable threw an error while handling the request.
`502 Bad Gateway`	Your server didn't start sending a response within 20 seconds, or the instance stopped before responding, for example because your server crashed or ran out of memory.

A request that reaches the request duration limit after your server has started responding has its connection closed, so the visitor receives an incomplete response.

When an instance stops unexpectedly, the next request starts a new one.

Common problems

Server receives no requests

Requests only reach your server when nothing else on your project handles them first. Refer to Routing for the order. Check for:

A catch-all rewrite rule, such as /* /index.html 200, which sends requests to its destination instead of your server. Limit it to the paths your frontend handles.
A static file at the same path, which always takes precedence over your server.
A function configured for the same path.
Your server's path and excludedPath, which may leave the path out.

Instance fails to start

When an instance fails to start, the request that started it gets a 500 response, and a production deploy whose server fails to start isn't published. Your logs show the error. Common causes are:

Top-level code or a start hook throws.
A server your code starts itself doesn't listen in time. It must start listening within 10 seconds of your start hooks finishing. Make sure it listens on process.env.PORT.
Your code starts more than one server, and none of them listens on process.env.PORT.

Responses after 20 seconds fail

Your server must send a response's status and headers within 20 seconds. For slow work, send the headers first and stream the rest of the response, or respond right away and finish the work with waitUntil.

Requests get a 429 response

The instance is handling as many requests as it can at once. A Server-Sent Events stream, or any other streamed response, holds one of those requests for as long as it's open. WebSocket connections don't, since they're counted separately. Refer to Request concurrency.

WebSocket upgrades get a 501 response

Your entry file exports an app directly, such as an Express app, which can't accept WebSocket connections. Start it with listen() instead. Refer to Real-time.

Outbound connections close after a minute

A connection your server keeps open to another service is closed after 60 seconds without any data. For example, a database connection waiting for LISTEN notifications stops receiving them, and your database client reports an error such as Connection terminated unexpectedly. Send something over the connection at least once every 60 seconds, or reconnect when it closes.

Environment variable changes have no effect

Environment variable values are fixed when you deploy. Redeploy for your server to receive the new values. Refer to Environment variables.

Files aren't found

Files your code reads at runtime, rather than imports, must be in your server's bundle. Add them with includedFiles, and resolve their paths relative to the module that reads them, rather than to the working directory.

To write files, use /tmp. The rest of the filesystem is read-only. Refer to Instance size.

Did you find this doc useful?

Your feedback helps us improve our docs.