Lifecycle

Your server runs as instances, which are running copies of your app that Netlify starts, stops, and replaces for you. This page describes what happens to an instance from when it starts until it stops, and how deploys move traffic from one version of your server to the next.

Instances

Each instance serves many requests at the same time, and keeps memory, connections, and caches between them. Time a request spends waiting, such as on a database query or a streaming model response, doesn't block the other requests the instance is handling.

Netlify scales the number of instances automatically, based on demand. It starts more as traffic grows, up to a limit, sends each new request to the instance with the most room, and stops instances as traffic falls, down to none when nothing is using your server. How much room an instance has depends on how busy it is.

In-memory state belongs to a single instance and is lost when that instance stops, and so is anything it writes to its local disk. Use them for connection pools, caches, warm clients, and temporary files, and use Netlify Blobs or Netlify Database for anything that must be durable.

An instance stops when it has gone a while without requests, when a newer deploy replaces it, and after it has been running for a while, even if it's busy. Refer to Limits for how long each of these takes.

Multiple instances

More than one instance of your server can be running at a time, even if traffic never makes it scale up. During a deploy, the new deploy's instances start while the previous deploy's instances finish their work. Instances are also replaced at least every 8 hours, whether or not you deploy, so any instance can stop while another one takes over.

To make sure your server works through these changes:

Treat in-memory data as a cache rather than the source of truth. Anything that must last or be shared between instances belongs in Netlify Database or Netlify Blobs.
Don't assume your server is the only instance running. Work that should happen once, such as sending a daily report, can run on two instances at the same time, or on neither while one stops and the next starts. Use a scheduled function for scheduled work, and record what's been done in a database so another instance doesn't repeat it.
Don't assume an instance keeps running. Save the progress of long-running work so another instance can pick it up.

Load-aware routing

Netlify judges how busy each instance is with Node.js runtime metrics, such as event loop utilization, rather than only generic CPU usage. Your code runs on a single JavaScript thread, so an instance can be too busy to take more work while its CPU usage looks low, and the event loop shows that where CPU usage doesn't. Netlify also tracks each instance's memory.

Your code can add custom metrics for resources only it knows about, such as a database connection pool or a job queue. Report how busy they are with an onHealthCheck hook, and Netlify weighs them alongside its own.

An instance is as busy as its busiest resource. When that resource is close to its capacity, the instance stops receiving new requests while other instances can take them, and Netlify starts more instances when every one of them is busy. A busy instance keeps running and serving the requests it already has.

A hook reports load, not whether your server is healthy, so an instance is never stopped or replaced because of what a hook reports.

Load-aware routing chooses between instances, so it takes effect whenever your server runs more than one.

Scale to zero

When your server isn't receiving traffic, Netlify stops its instances, so nothing runs until the next request arrives. A server with occasional traffic doesn't keep an idle process running, which keeps it cost-efficient.

When an instance stops

An instance stops after 5 minutes without requests. The timer starts over every time a request finishes, and doesn't run while the instance has any of the following:

Requests in progress.
Open WebSocket and Server-Sent Events connections.
Background work passed to waitUntil.

Work you start any other way, such as a timer created with setInterval, doesn't keep the instance running. Before the instance stops, it shuts down like any other, so your shutdown hooks run.

Cold starts

When a request arrives and no instance is running, Netlify starts a new one, and the request waits for your server to start. This includes loading your entry file and running your start hooks, so the request takes longer than one served by a running instance. The time it takes counts toward the 20 seconds your server has to send the response's headers.

To keep that wait short:

Limit your entry file's top-level code and your start hooks to what your server needs before its first request. Set up services or data that only some routes use when a request first needs them.
Keep your server's dependencies small, since they're loaded every time an instance starts.

A production deploy's server is already running when the deploy goes live, so visitors don't wait for it after you ship. Refer to Deploys.

Startup

When an instance starts, Netlify loads your entry file, which runs its top-level code. If that code uses top-level await, loading waits for it. Netlify then runs your start hooks, if you registered any, and finds the server to send requests to, depending on what your entry file exports. The instance receives no traffic until all of this has finished.

If any of it throws an error or exception, the instance fails to start.

Shutdown

When an instance is being stopped, for example because you deployed a new version or because traffic dropped, Netlify stops sending it new requests and runs the following steps, in order:

Delivers a SIGTERM signal to the process, so that unmodified apps and libraries that handle the signal for graceful shutdown work without any changes.
Stops your server, if your entry file exports one or starts one, from accepting new connections.
Starts your shutdown hooks, which run in parallel.
Waits for the requests in progress, including open WebSocket and Server-Sent Events connections, and for background work to finish, for up to 90 seconds.
Waits for your shutdown hooks to finish, for up to 115 seconds from when they started.
Closes any connections that are still open, and stops the instance.

Requests and background work that take longer than 90 seconds are cut off, so a client running a long request should be ready to retry it.

Your shutdown hooks run alongside that work. Use them to explicitly stop work that would otherwise keep running, such as open WebSocket connections, so the instance doesn't wait for it. Then await drained, which resolves once the work in progress has finished, before closing the resources it uses. This leaves your hooks at least 25 seconds after the work ends:

import { getWebSockets, onShutdown } from "@netlify/server";

onShutdown(async ({ drained }) => {
  for (const socket of getWebSockets()) {
    socket.close(1012, "Server restarting");
  }

  await drained;
  await pool.end();
});

If your code handles SIGTERM and then exits the process, for example with server.close(() => process.exit(0)), background work and shutdown hooks that are still running are cut off. Netlify stops the instance once that work has finished, so we recommend that you don't call process.exit() yourself.

Background work

To do work after you respond, such as sending an email, recording analytics, or continuing an agent loop that runs for several minutes, pass its promise to waitUntil on the request's Context. The response goes out right away, and Netlify keeps the instance running until the promise settles, rather than stopping it for inactivity while the work is still going on. Background work isn't limited by the request duration.

import type { Context } from "@netlify/server";

export default async (req: Request, context: Context) => {
  const { pathname } = new URL(req.url);

  if (req.method === "POST" && pathname === "/api/orders") {
    const order = await saveOrder(await req.json());

    context.waitUntil(sendConfirmationEmail(order));

    return Response.json(order, { status: 201 });
  }

  return new Response("Not found", { status: 404 });
};

import express from "express";
import { getContext } from "@netlify/server";

const app = express();

app.use(express.json());

app.post("/api/orders", async (req, res) => {
  const { waitUntil } = getContext();
  const order = await saveOrder(req.body);

  res.status(201).json(order);

  waitUntil(sendConfirmationEmail(order));
});

app.listen(process.env.PORT);

import { Hono } from "hono";
import { getContext } from "@netlify/server";

const app = new Hono();

app.post("/api/orders", async (c) => {
  const { waitUntil } = getContext();
  const order = await saveOrder(await c.req.json());

  waitUntil(sendConfirmationEmail(order));

  return c.json(order, 201);
});

export default app;

import Fastify from "fastify";
import { getContext } from "@netlify/server";

const app = Fastify();

app.post("/api/orders", async (request, reply) => {
  const { waitUntil } = getContext();
  const order = await saveOrder(request.body);

  waitUntil(sendConfirmationEmail(order));

  return reply.code(201).send(order);
});

await app.listen({ port: Number(process.env.PORT) });

A handler or a Fetchable can also call waitUntil on the context it receives as its second argument, as in the Handler example. If the promise rejects, the error is logged, and your server keeps running.

Work you start without waitUntil is invisible to Netlify, so an instance with no requests in progress can be stopped while that work is still running.

When an instance is replaced, whether because of a new deploy or a scaling event, Netlify gives background work in progress up to 90 seconds to finish as part of its shutdown. For critical work where you expect longer background tasks, we recommend persisting it to Netlify Database or Netlify Blobs, so that another instance of your server can pick it up.

Deploys

Every deploy runs the server that was deployed with it, and rolling back a deploy rolls back its server too.

When you publish a deploy to production, Netlify starts its server alongside the one that's currently serving, and waits until an instance of the new server is ready, including any start hooks. Only then does it publish the deploy and move traffic to it:

If the new server fails to start, the deploy isn't published, and production keeps running the previous version.
Once traffic has moved, the previous deploy's instances are stopped gracefully.
The new server is already running when the deploy goes live, so the first visitors after a deploy don't wait for it to start.

For a short time, instances of both deploys are running at once. Refer to Multiple instances.

If neither your server's code nor its configuration has changed since the previous deploy, publishing skips this step and keeps the running server.

Branch deploys and Deploy Previews start their server on the first request they receive, so your backend is part of every preview without affecting production.

Did you find this doc useful?

Your feedback helps us improve our docs.