Basics

What is graceful shutdown — why someone loses their request on every deploy

Illustration: a 'closed' sign up front while the last guest finishes

You ship an update. Clean run, green check, zero errors in the logs.

At that exact moment three people had their request cut off mid-flight. One of them was paying.

You never saw it — the server was already dead and had nothing left to log it with. Let's look at how an app should die.

What actually happens on a deploy

The new version doesn't appear on top of the old one. The old one gets switched off first.

Switching off looks like this: the process gets a SIGTERM signal — a polite "wrap it up". Then the system waits. Not done in time? SIGKILL arrives, and that one isn't a request, it's pulling the plug.

In Kubernetes the waiting window defaults to 30 seconds (terminationGracePeriodSeconds). For docker stop it's 10 by default. Same idea either way: you get those seconds to finish what you started.

Graceful shutdown is your app knowing how to use them.

What has to happen in those seconds

Order matters more than speed. The right sequence:

  1. Stop accepting new requests. Close the door to new connections, but don't cut the open ones.
  2. Let the in-flight ones finish. The person submitting a form right then deserves an answer.
  3. Close what's open. Database connections, files, background job queues.
  4. Exit on your own, without waiting for SIGKILL.

In code that's one signal subscription. In Node.js literally process.on('SIGTERM', ...), with server.close() and the database teardown inside. Without it the process just dies instantly, cutting everything off mid-sentence.

The trap: the signal never arrived

Here's the surprising part.

You wrote the handler, tested locally, it works. Inside a container it does nothing at all, as if the code weren't there.

The cause is how the start command is written in your Dockerfile. There are two forms:

  • CMD npm start — the shell form;
  • CMD ["npm", "start"] — the exec form.

In the first one Docker doesn't launch your program, it launches /bin/sh -c, and the shell launches your program as a child process. The Docker docs say it word for word: the shell "does not pass signals", your executable is not PID 1 "and will not receive Unix signals". And then plainly: your executable doesn't receive a SIGTERM from docker stop.

So the handler exists, but nothing ever calls it. The container hangs silently for its 10 seconds and dies of SIGKILL.

The fix is square brackets. Use the exec form and the signal lands where it should.

Order with a balancer: leave the rotation first

The second gotcha is subtle and long-lived.

Say you did everything right and you're finishing in-flight requests. But your load balancer doesn't know that and keeps sending you new people — whom you're no longer accepting. They get an error.

That's why Kubernetes removes the pod from the list of live endpoints at roughly the same moment it sends SIGTERM — but that news doesn't spread through the system instantly.

The practical takeaway is simple: first say "I'm not ready any more", wait a couple of seconds, and only then start closing. Those two seconds look like doing nothing, and they're exactly what removes the errors from every deploy.

Where you'll meet this

Everywhere an app restarts — so on every deploy, every rollback, every autoscaling event, every restart of a crashed process.

While it's one side project with three users, nobody notices a dropped request. The moment there are payments, uploads and background jobs, graceful shutdown stops being theory.

How to check that it works

Two minutes to test, and worth doing before you ship payments.

  1. Run the app locally and find its process id — ps, or whatever the program prints.
  2. Fire a request that's guaranteed to be slow. Any endpoint with an artificial 5-second delay will do.
  3. While it's hanging, send the process that same signal: kill -TERM plus the process id. -TERM specifically, not -9 — nine is SIGKILL and nothing can intercept it.
  4. Watch two things: did the pending request get its answer, and did your shutdown line appear in the console.

Both happened — you're fine. Cut off instantly — there's no handler, or the signal isn't reaching it.

Same trick with a container: docker stop and a stopwatch. A container that honestly dies in a second and a container that reliably hangs for exactly 10 seconds are two different diagnoses. The second one means SIGKILL on timeout.

Can I just raise the timeout?

No. If the app doesn't listen for the signal, it won't close any more carefully because you gave it 120 seconds instead of 30. It will just hang around longer and still die hard. You tune the window after the handler exists, not instead of it.

What if a request takes longer than the grace period?

Then it gets cut anyway. Long operations — a five-minute report, video processing — shouldn't live inside a request. Move them into a background job so a server restart doesn't kill them.

What if my host doesn't use Docker?

Same mechanics. Every platform sends the process a termination signal before a restart and waits. Only the setting names and the window length change — you need the handler either way.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →