What causes "All statistics values must be non-negative" in redis/node-redis?

Use CacheStats.empty() or the factory defaults instead of constructing values yourself.

redis/node-redis · error · Error

All statistics values must be non-negative

Error message

All statistics values must be non-negative

What it means

CacheStats is constructed with six counters (hitCount, missCount, loadSuccessCount, loadFailureCount, totalLoadTime, evictionCount). All must be non-negative because cache counters are monotonic by definition; the constructor rejects any negative value. Used to validate stats snapshots created via CacheStats.of(...).

Solutions

Use CacheStats.empty() or the factory defaults instead of constructing values yourself.
Clamp deltas with Math.max(0, x) before passing them in.
Fix the differencing logic to never go negative (counters are monotonic).

Example fix

// before
CacheStats.of(a.hitCount - b.hitCount, a.missCount - b.missCount, ...);

// after
CacheStats.of(
  Math.max(0, a.hitCount - b.hitCount),
  Math.max(0, a.missCount - b.missCount),
  ...
);

Defensive patterns

Strategy: validation

Validate before calling

function safeStatsOf(hit, miss, loadOk, loadFail, loadTime, evict) {
  const vals = [hit, miss, loadOk, loadFail, loadTime, evict];
  if (vals.some(v => typeof v !== 'number' || Number.isNaN(v) || v < 0)) {
    throw new Error('All CacheStats values must be finite non-negative numbers');
  }
  return CacheStats.of(hit, miss, loadOk, loadFail, loadTime, evict);
}

Prevention

Never subtract CacheStats counters naively; clamp with Math.max(0, a - b).
Use CacheStats.empty() as the base rather than constructing zeros manually.
Guard against NaN/undefined flowing in from deserialization.

When it happens

Trigger: Calling CacheStats.of with a negative argument for any of the six counters; a differencing computation that subtracts in the wrong order; deserialization that lost sign information.

Common situations: Building a delta between two CacheStats snapshots by naive subtraction (a - b when b > a); passing through a NaN/undefined that became negative after coercion; incorrect manual stats aggregation.

Related errors

AI-assisted analysis of redis/node-redis@90fd0652bc (2026-08-11). Data as JSON: /api/errors/e4e61100aec4b8f8. Report an issue: GitHub.

Appendix: source

Thrown at packages/client/lib/client/cache.ts:51

   * Creates a new CacheStats instance with the specified statistics.
   */
  private constructor(
    public readonly hitCount: number,
    public readonly missCount: number,
    public readonly loadSuccessCount: number,
    public readonly loadFailureCount: number,
    public readonly totalLoadTime: number,
    public readonly evictionCount: number
  ) {
    if (
      hitCount < 0 ||
      missCount < 0 ||
      loadSuccessCount < 0 ||
      loadFailureCount < 0 ||
      totalLoadTime < 0 ||
      evictionCount < 0
    ) {
      throw new Error('All statistics values must be non-negative');
    }
  }

  /**
   * Creates a new CacheStats instance with the specified statistics.
   *
   * @param hitCount - Number of cache hits
   * @param missCount - Number of cache misses
   * @param loadSuccessCount - Number of successful cache loads
   * @param loadFailureCount - Number of failed cache loads
   * @param totalLoadTime - Total load time in milliseconds
   * @param evictionCount - Number of cache evictions
   */
  static of(
    hitCount = 0,
    missCount = 0,
    loadSuccessCount = 0,
    loadFailureCount = 0,

View on GitHub (pinned to 90fd0652bc)