This RangeError occurs when passing a timeout value that exceeds the maximum 32-bit unsigned integer limit (4,294,967,295 milliseconds, about 49.7 days) to timer functions like setTimeout or setInterval.
This error indicates that a timeout value passed to Node.js timer functions (setTimeout, setInterval, or other timeout-accepting APIs) falls outside the valid range of 0 to 4,294,967,295 milliseconds. The number 4,294,967,295 represents the maximum value for a 32-bit unsigned integer (2^32 - 1). This is approximately 49.7 days in milliseconds. Node.js enforces this limit because internally, timer functions store timeout values as 32-bit unsigned integers. While this error message specifically mentions the upper limit of 4,294,967,295, note that many JavaScript implementations also have a practical limit for signed 32-bit integers (2,147,483,647 milliseconds, about 24.8 days). Exceeding either limit will trigger range validation errors depending on the specific function and Node.js version.
Review the code where you're setting the timeout and verify the value being passed:
// This will fail - 60 days exceeds the limit
setTimeout(() => {
console.log('Delayed action');
}, 60 * 24 * 60 * 60 * 1000); // 5,184,000,000 ms
// Check the calculated value
const timeoutMs = 60 * 24 * 60 * 60 * 1000;
console.log('Timeout value:', timeoutMs);
console.log('Max allowed:', 4294967295);If your calculated value exceeds 4,294,967,295, you'll need to use an alternative approach.
Define and use the maximum safe timeout constant in your code:
// Maximum timeout value for Node.js
const MAX_TIMEOUT = 2147483647; // ~24.8 days (signed 32-bit limit)
// Clamp your timeout to the maximum
function setSafeTimeout(callback, delay) {
const safeDelay = Math.min(delay, MAX_TIMEOUT);
return setTimeout(callback, safeDelay);
}
// Usage
setSafeTimeout(() => {
console.log('This will work');
}, 60 * 24 * 60 * 60 * 1000);This approach prevents the error by capping timeouts at a safe value.
For delays exceeding the limit, chain multiple shorter timeouts:
function longTimeout(callback, totalDelay) {
const MAX_TIMEOUT = 2147483647;
if (totalDelay <= MAX_TIMEOUT) {
return setTimeout(callback, totalDelay);
}
// Split into chunks
return setTimeout(() => {
longTimeout(callback, totalDelay - MAX_TIMEOUT);
}, MAX_TIMEOUT);
}
// Schedule callback for 60 days from now
longTimeout(() => {
console.log('Executed after 60 days');
}, 60 * 24 * 60 * 60 * 1000);This recursively schedules timeouts until the full delay is achieved.
For production applications needing long delays, use a dedicated scheduling solution:
// Using node-cron for scheduled tasks
import cron from 'node-cron';
// Schedule task to run at specific time
cron.schedule('0 0 * * *', () => {
console.log('Running daily task');
});
// Or use node-schedule for more complex scheduling
import schedule from 'node-schedule';
// Schedule for specific date/time
const date = new Date(Date.now() + (60 * 24 * 60 * 60 * 1000));
schedule.scheduleJob(date, () => {
console.log('Executed at scheduled time');
});These libraries handle long delays internally and persist across application restarts.
Add validation to prevent invalid timeout values from being used:
function validateTimeout(delay) {
const MAX_TIMEOUT = 4294967295;
if (typeof delay !== 'number' || isNaN(delay)) {
throw new TypeError('Timeout must be a number');
}
if (delay < 0) {
throw new RangeError('Timeout cannot be negative');
}
if (delay > MAX_TIMEOUT) {
throw new RangeError(
`Timeout exceeds maximum: ${delay} > ${MAX_TIMEOUT}`
);
}
return delay;
}
// Use with setTimeout
const delay = validateTimeout(myCalculatedDelay);
setTimeout(callback, delay);This catches issues early with clear error messages.
Understanding the limits: JavaScript engines store timeout values as 32-bit integers. While the error message mentions 4,294,967,295 (unsigned 32-bit max), many implementations use signed 32-bit integers with a practical limit of 2,147,483,647 milliseconds. When exceeded, behavior varies: some implementations trigger immediate execution, others throw errors, and newer versions enforce strict validation.
Performance considerations: Chained timeouts work but can lead to memory leaks if not properly cleared. Always store timeout IDs and clear them when appropriate:
let timeoutId;
function startLongTimeout(callback, delay) {
const MAX = 2147483647;
if (delay <= MAX) {
timeoutId = setTimeout(callback, delay);
} else {
timeoutId = setTimeout(() => {
startLongTimeout(callback, delay - MAX);
}, MAX);
}
}
function cancelLongTimeout() {
if (timeoutId) {
clearTimeout(timeoutId);
timeoutId = null;
}
}Database-backed scheduling: For production systems requiring reliable long-term scheduling, consider database-backed solutions like Bull (Redis-based job queue) or Agenda (MongoDB-based scheduler). These persist scheduled tasks and handle application restarts gracefully.
Testing edge cases: When working with timeouts, test boundary conditions:
- Zero timeout (immediate execution)
- Maximum safe value (2,147,483,647)
- Just above maximum (should fail or be handled)
- Negative values (should be rejected)
Platform differences: Browser implementations of setTimeout/setInterval have similar limits but may enforce them differently. Always validate timeout values in cross-platform code.
Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: EACCES: permission denied, open '/root/file.txt'
EACCES: permission denied
Error: Invalid encoding specified (stream encoding not supported)
How to fix Invalid encoding error in Node.js readable streams
Error: EINVAL: invalid argument, open
EINVAL: invalid argument, open
TypeError: readableLength must be a positive integer (stream config)
TypeError: readableLength must be a positive integer in Node.js streams