Countdown Timer API vs setTimeout

It dies with the process

This is the one that reaches production, because it works perfectly on a developer machine that never restarts during a test.

// Looks fine. Works in development. Fails in production.
function startTrial(customer) {
  setTimeout(() => {
    downgradeAccount(customer.id);
  }, 14 * 24 * 60 * 60 * 1000);   // 14 days
}

// Deploy, restart, crash, scale-to-zero, or a new container —
// the callback is gone and nothing records that it was lost.

A pending setTimeout is a closure on a heap. It has no representation outside that process, so anything that ends the process ends the timer: a deploy, a crash, an out-of-memory kill, a container being rescheduled, an autoscaler removing an instance, or a serverless runtime freezing between invocations.

Nothing is logged when this happens, because nothing failed. There is no error, no dead letter, and no record that a callback was ever pending. You find out when a customer keeps a paid feature for a month.

It silently overflows past 24.8 days

The delay is stored as a signed 32-bit integer. Exceed it and the value wraps, and the callback fires immediately instead of a month later.

// The 32-bit trap. setTimeout stores the delay as a signed
// 32-bit integer: anything over 2,147,483,647 ms overflows.
const THIRTY_DAYS = 30 * 24 * 60 * 60 * 1000;   // 2,592,000,000

setTimeout(() => console.log("fires in 30 days"), THIRTY_DAYS);
// Actually fires IMMEDIATELY. The value wraps and is treated as 1.
//
// Max safe delay: 2147483647 ms = 24 days, 20 hours, 31 minutes.
// No warning. No error. Just an instant callback.

This behaviour is specified and consistent — Node.js emits a warning in some versions, browsers do not. A 30-day trial, a 90-day retention window, or an annual renewal reminder all cross the line. The bug does not look like a timing bug; it looks like the action happening instantly on signup, which sends people hunting in entirely the wrong place.

On the client it counts the wrong clock

A browser setTimeout measures against the visitor's system clock, which you do not control and cannot trust.

// The client-side version, which is a different bug.
const remaining = deadline - Date.now();   // the VISITOR's clock

setTimeout(showExpired, remaining);
// - System clock is wrong  -> fires early or late
// - Laptop lid closed      -> timer suspends, fires late
// - Tab backgrounded       -> throttled to >=1s, then >=1min
// - User changes the clock -> deadline beaten deliberately
// - Page refreshed         -> timer gone entirely

Background-tab throttling alone breaks most countdown UIs: after a few minutes hidden, the tab's timers drop to roughly one tick per minute, so a countdown that looked smooth reappears having jumped. And on anything with money attached, a visitor who moves their system clock forward walks past a deadline that only ever existed in their browser.

What replaces it

The deadline moves out of process memory and becomes a record. Whatever is running in fourteen days receives the callback — it does not have to be the process that created it, or even the same deployment.

// The deadline outlives the process that created it.
await call("/timers", {
  method: "POST",
  headers: { "Idempotency-Key": `trial_${customer.id}` },
  body: JSON.stringify({
    name: `Trial — ${customer.email}`,
    type: "personalized",
    duration_seconds: 14 * 24 * 60 * 60,
    external_user_id: customer.id,
  }),
});

// Fourteen days later, in whatever process happens to be running:
app.post("/webhooks/countdownshare", (req, res) => {
  res.sendStatus(200);
  queue.add("downgrade-account", JSON.parse(req.body));
});

When setTimeout is correct

Most of the time, in fact. It is a good primitive being asked to do a job it was never designed for.

The dividing line is ownership. If setTimeout is animating a number, it is doing its job. If it is the only record that something must happen, it is a single point of failure with no alarm attached.

The pattern that uses both correctly

Read the authoritative remaining time once, then let setTimeout or setInterval animate between reads. The server owns the truth; the browser owns the smoothness.

Common questions

Related