Step-by-step guide

Next.js Graceful Shutdown and Health Checks

Configure useful Next.js readiness checks and graceful shutdown so deploys stop new traffic and drain in-flight work safely.

By HostNextJS Editorial TeamReviewed by HostNextJS Technical Review Published Updated
01Typeguide
02Last reviewed
03Update policyReview every 90 days.
At a glance

Deployment sequence

  1. STEP 01

    Define health signals

    Separate process liveness from readiness to receive traffic and post-deploy functional checks.

  2. STEP 02

    Remove traffic first

    Mark the instance unready and allow proxies or load balancers to stop new requests.

  3. STEP 03

    Send a graceful signal

    Use SIGTERM or SIGINT and allow Next.js to finish in-flight requests and pending after callbacks.

  4. STEP 04

    Enforce a drain budget

    Use a 10-30 second configurable period, observe completion, then force termination only after timeout.

A useful health system answers more than “is a process listening?” Liveness decides whether to restart it. Readiness decides whether to send it traffic. Post-deploy checks decide whether the release behaves correctly.

Keep checks bounded

Expose a lightweight route that can report the release identity and readiness state without leaking secrets. Liveness should avoid slow external dependencies. Readiness may check dependencies essential to serving traffic, but every check needs a short timeout so the monitor cannot create an outage.

Drain before stopping

On deployment or shutdown, remove the instance from new traffic, then send SIGTERM or SIGINT. Current Next.js guidance says the server finishes in-flight requests and pending after() callbacks; it recommends a configurable 10–30 second drain period. Align the supervisor, container, and load-balancer timeouts so a shorter outer timeout does not interrupt the drain.

Test failure paths

Verify startup failure, dependency failure, an in-flight slow response during termination, a stuck shutdown, and forced termination after the deadline. Do not catch an uncaught exception and continue serving; Node.js recommends an external monitor restart a crashed process.

Methodology

How this resource was produced

This guide distinguishes liveness, readiness, startup verification, and graceful drain instead of treating one 200 response as complete health.

Limitations
  • 01

    A health endpoint cannot prove every dependency or user journey is healthy.

  • 02

    SIGKILL and machine loss cannot be drained; critical work needs durable design.

Evidence

Sources and review record

Primary documentation checked for the material claims on this page. Product behavior and prices can change after the checked date.

  1. 01 · Next.jsHow to self-host Next.jsChecked July 12, 2026
  2. 02 · Node.jsNode.js signal eventsChecked July 12, 2026
Next step

Turn the resource into a deployment decision.

Review your release health checks