nodejs/node · error · TypeError

SqliteCacheStore options.maxEntrySize must be less than 2gb

Error message

SqliteCacheStore options.maxEntrySize must be less than 2gb

What it means

Thrown when opts.maxEntrySize is a valid non-negative integer but exceeds MAX_ENTRY_SIZE (the 2 GiB ceiling). SQLite blob/page limits make entries above ~2 GB impractical, so the store refuses them up front rather than failing later on a write.

Source

Thrown at deps/undici/src/lib/cache/sqlite-cache-store.js:94

   * @param {import('../../types/cache-interceptor.d.ts').default.SqliteCacheStoreOpts | undefined} opts
   */
  constructor (opts) {
    if (opts) {
      if (typeof opts !== 'object') {
        throw new TypeError('SqliteCacheStore options must be an object')
      }

      if (opts.maxEntrySize !== undefined) {
        if (
          typeof opts.maxEntrySize !== 'number' ||
          !Number.isInteger(opts.maxEntrySize) ||
          opts.maxEntrySize < 0
        ) {
          throw new TypeError('SqliteCacheStore options.maxEntrySize must be a non-negative integer')
        }

        if (opts.maxEntrySize > MAX_ENTRY_SIZE) {
          throw new TypeError('SqliteCacheStore options.maxEntrySize must be less than 2gb')
        }

        this.#maxEntrySize = opts.maxEntrySize
      }

      if (opts.maxCount !== undefined) {
        if (
          typeof opts.maxCount !== 'number' ||
          !Number.isInteger(opts.maxCount) ||
          opts.maxCount < 0
        ) {
          throw new TypeError('SqliteCacheStore options.maxCount must be a non-negative integer')
        }
        this.#maxCount = opts.maxCount
      }
    }

    if (!DatabaseSync) {

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Lower the value below 2 GiB: new SqliteCacheStore({ maxEntrySize: 1024 * 1024 * 1024 }).
2. If you genuinely need huge entries, do not use SqliteCacheStore — pick a filesystem-backed store.
3. Confirm you are passing bytes, not a larger unit.
4. Omit the option to fall back to the default cap.

Example fix

// before
new SqliteCacheStore({ maxEntrySize: 5 * 1024 * 1024 * 1024 })
// after
new SqliteCacheStore({ maxEntrySize: 1024 * 1024 * 1024 })

const MAX_ENTRY_SIZE = 2 * 1024 * 1024 * 1024
if (opts.maxEntrySize != null && opts.maxEntrySize > MAX_ENTRY_SIZE) {
  throw new RangeError('maxEntrySize must be < 2 GiB')
}

function isWithinMaxEntrySize(v) {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 2 * 1024 ** 3
}

When it happens

Trigger: Passing maxEntrySize larger than 2 * 1024 * 1024 * 1024 (e.g. 3e9 or 5 * 1024**3). Most common when the value was computed in MB or GB and multiplied incorrectly.

Common situations: Assuming the unit is megabytes; pulling a value from a shared config meant for disk cache size; copy-pasting a large CDN-style number into a single-entry cap.

Related errors

• SqliteCacheStore options must be an object
• SqliteCacheStore options.maxEntrySize must be a non-negative
• SqliteCacheStore options.maxCount must be a non-negative int
• expected key to be object, got ${typeof key}
• MemoryCacheStore options must be an object

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/3085d1e8bdeebd7d. Report an issue: GitHub.