Skip to content
Node.js: Reject timer delays outside the supported range

Node.js: Reject timer delays outside the supported range

November 18, 2026

A large delay can make a Node.js timer run almost immediately. Node sets delays greater than 2,147,483,647 milliseconds to 1 millisecond. Validate configuration before passing it to a timer, especially when converting days or seconds into milliseconds.

Set up

Tested on Debian 13 Linux with Node.js v24.19.0. Use Bash, Node.js on your PATH, a text editor, and the mktemp, rm and rmdir utilities. No packages or network access are needed. Keep the same terminal through cleanup. Stop if setup fails before saving the source.

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save as node-validate-timer-delay.mjs:

import assert from 'node:assert/strict';
import { setTimeout as delay } from 'node:timers/promises';

function timerMilliseconds(value) {
  if (!Number.isInteger(value) || value < 1 || value > 2_147_483_647) {
    throw new RangeError('Expected 1 through 2147483647 integer milliseconds');
  }
  return value;
}

assert.equal(timerMilliseconds(1), 1);
assert.equal(timerMilliseconds(2_147_483_647), 2_147_483_647);
const rejected = [0, -1, 1.5, 2_147_483_648, NaN, Infinity, '1000', null];
for (const value of rejected) {
  assert.throws(() => timerMilliseconds(value), RangeError);
}

await delay(timerMilliseconds(1));
console.log('Accepted endpoints: 1, 2147483647');
console.log('Rejected invalid values:', rejected.length);
console.log('One short timer completed');

Run:

node node-validate-timer-delay.mjs

Observed output:

Accepted endpoints: 1, 2147483647
Rejected invalid values: 8
One short timer completed

Validate before scheduling

The guard accepts only integer Number values from 1 through 2,147,483,647. Both endpoints are tested, but only the 1-millisecond timer is scheduled. The upper-end assertion validates the number without waiting for a long timer. The test checks completion, not elapsed-time precision.

Node’s timer documentation specifies a 1-millisecond delay for values greater than 2,147,483,647, less than 1, or NaN. Non-integer delays are truncated. This helper rejects those inputs instead of accepting an implicit adjustment. It also rejects strings, null and Infinity.

Validate the final millisecond value after unit conversion. A value that is valid in seconds can exceed the timer range after multiplication. Treat units as part of the configuration format, and report a range error to the caller instead of starting an unexpectedly short retry loop.

Limits of an in-process timer

Node does not guarantee the exact time at which a timeout callback runs. Other work on the event loop can delay it.

The maximum delay is about 24.9 days. Longer schedules need a different design, such as a persisted deadline checked periodically. A process restart also loses an ordinary in-memory timer. Choose persistence and recovery behavior according to the job; increasing the numeric delay does not provide either.

Clean up

Remove the saved file and empty scratch directory. If the directory is not empty, inspect its contents before removing anything else.

rm -- node-validate-timer-delay.mjs
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on