[BUG] MediaLocalStorage: setTimeout 32-bit overflow deletes files immediately when WHATSAPP_FILES_LIFETIME > ~24.8 days

[niels-przybilla]

Bug Description

MediaLocalStorage.postponeRemoval() uses setTimeout(fn, this.lifetimeMs) to schedule file deletion. When WHATSAPP_FILES_LIFETIME exceeds ~24.8 days (2,147,483 seconds), the resulting millisecond value overflows JavaScript's 32-bit signed integer limit for setTimeout delays (max: 2,147,483,647 ms).

Node.js silently converts the overflowed value to 1 millisecond, causing files to be deleted immediately after creation.

Steps to Reproduce

1. Set WHATSAPP_FILES_LIFETIME=2592000 (30 days, the value many users would choose for "keep files for a month")
2. Start WAHA, connect a session
3. Receive a media message or call the messages API with downloadMedia=true
4. Observe that media URLs return 404 even though download appears to succeed

Expected Behavior

Files should be kept for 30 days as configured.

Actual Behavior

Files are written to disk and then deleted within 1ms due to setTimeout overflow. Node.js emits a TimeoutOverflowWarning but this is not logged by WAHA.

(node) TimeoutOverflowWarning: 2592000000 does not fit into a 32-bit signed integer.
Timeout duration was set to 1.

Root Cause

In src/core/media/local/MediaLocalStorage.ts, line ~92:

private postponeRemoval(filepath: string) {
    if (this.lifetimeMs === 0) {
      return;
    }
    setTimeout(
      () => fs.unlink(filepath, () => { ... }),
      this.lifetimeMs,  // <-- overflows when > 2,147,483,647
    );
  }

this.lifetimeMs = lifetimeSeconds * SECOND where SECOND = 1000. Any WHATSAPP_FILES_LIFETIME value > 2,147,483 seconds (~24.85 days) triggers the overflow.

Suggested Fix

Option A: Cap the timeout at the 32-bit limit:

const MAX_TIMEOUT = 2_147_483_647; // ~24.8 days
setTimeout(fn, Math.min(this.lifetimeMs, MAX_TIMEOUT));

Option B: Use setInterval to check file age instead of setTimeout.

Option C: Document the maximum value and validate at startup.

Environment

• WAHA Plus: devlikeapro/waha-plus:dev
• Engine: GOWS
• Node.js: v24.11.1
• WHATSAPP_FILES_LIFETIME=2592000

Workaround

Set WHATSAPP_FILES_LIFETIME=0 (disables in-app cleanup) and use an external cron job to clean old files:

# Daily cleanup of files older than 7 days
0 3 * * * find /path/to/media -type f -mtime +7 -delete

Or set WHATSAPP_FILES_LIFETIME to a value < 2147483 (e.g., 2000000 for ~23 days).

[devlikepro]

2026.4.1 - Fix WHATSAPP_FILES_LIFETIME 32-bit setTimeout overflow causing immediate file deletion - #2018, #2019