pydantic/monty · error · Error

memoryUsageLimit must be a non-negative safe integer

Error message

memoryUsageLimit must be a non-negative safe integer

What it means

MountDir's memoryUsageLimit must be a non-negative Number safe integer (it bounds per-mount memory for overlay mounts). Values that are negative, fractional, NaN, or beyond Number.MAX_SAFE_INTEGER throw this Error in the constructor.

Source

Thrown at crates/monty-js/ts/mountDir.ts:59

  readonly writeBytesLimit: number | null
  readonly memoryUsageLimit: number
  /** The opened host directory, shared by every feed this mount is passed to.
   *  Symbol-keyed, so it stays off the public surface — see [`NATIVE_MOUNT`]. */
  readonly [NATIVE_MOUNT]: NativeMountDir

  constructor(options: MountDirOptions) {
    const mode = options.mode ?? 'overlay'
    // hasOwn, not `in`: prototype keys like 'toString' must not pass as modes
    if (!Object.hasOwn(VALID_MODES, mode)) {
      throw new Error(`invalid mount mode: '${mode}'. Expected 'read-only', 'read-write' or 'overlay'`)
    }
    this.hostPath = options.hostPath
    this.virtualPath = options.virtualPath
    this.mode = mode
    this.writeBytesLimit = options.writeBytesLimit ?? null
    this.memoryUsageLimit = options.memoryUsageLimit ?? DEFAULT_MEMORY_USAGE_LIMIT
    if (!Number.isSafeInteger(this.memoryUsageLimit) || this.memoryUsageLimit < 0) {
      throw new Error('memoryUsageLimit must be a non-negative safe integer')
    }
    // Opens the directory, so a bad host path throws here rather than at the
    // first feed — and every feed then mounts this descriptor, which no rename
    // of the host path can redirect.
    this[NATIVE_MOUNT] = new NativeMountDir({
      virtualPath: this.virtualPath,
      hostPath: this.hostPath,
      mode: this.mode,
      memoryUsageLimit: this.memoryUsageLimit,
      ...(this.writeBytesLimit !== null ? { writeBytesLimit: this.writeBytesLimit } : {}),
    })
  }

  /** Releases the open host directory. Later feeds using this mount throw;
   *  the properties above keep answering. Idempotent.
   *
   *  Only Windows needs this: it refuses to rename or delete a directory while
   *  a handle to it is open, so a mount left open blocks the host from touching

View on GitHub (pinned to adc986b362)

Solutions

Pass a non-negative integer byte count, e.g. 100 * 1024 * 1024
Omit memoryUsageLimit to use DEFAULT_MEMORY_USAGE_LIMIT
Validate before constructing: Number.isSafeInteger(v) && v >= 0

Example fix

// before
new MountDir({ hostPath: './data', virtualPath: '/mnt/data', memoryUsageLimit: 1.5 });
// after
new MountDir({ hostPath: './data', virtualPath: '/mnt/data', memoryUsageLimit: 100 * 1024 * 1024 });

Defensive patterns

Strategy: validation

Validate before calling

function assertByteLimit(v) {
  if (v !== undefined && (!Number.isSafeInteger(v) || v < 0)) {
    throw new Error(`memoryUsageLimit must be a non-negative safe integer, got ${v}`);
  }
}
assertByteLimit(opts.memoryUsageLimit);

Type guard

function isValidByteLimit(v) {
  return v === undefined || (Number.isSafeInteger(v) && v >= 0);
}

Try / catch

try {
  const dir = new MountDir({ hostPath, virtualPath, memoryUsageLimit });
} catch (e) {
  if (e instanceof Error && e.message.includes('memoryUsageLimit must be a non-negative safe integer')) {
    throw new Error('memoryUsageLimit must be an integer byte count >= 0, e.g. 100 * 1024 * 1024');
  }
  throw e;
}

Prevention

Express limits as integer byte counts built from Math.floor and integer multipliers
Parse size strings ('100MB') through a strict parser that yields safe integers
Omit the option to accept the library default when unsure

When it happens

Trigger: new MountDir({ ..., memoryUsageLimit: -1 }), memoryUsageLimit: 1.5, a value parsed loosely from a string ('104857600' via Number on a malformed input giving NaN), or a limit in bytes exceeding 2**53-1.

Common situations: Limits computed by multiplying unvalidated numbers; parsing '100 MB' style strings; copying a byte limit expressed in a wider type from another language or config system.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of pydantic/monty@adc986b362 (2026-09-13). Data as JSON: /api/errors/4537506cfbd4732a. Report an issue: GitHub.