vitest-dev/vitest · error · Error

For a percentage based memory limit a percentageReference mu

Error message

For a percentage based memory limit a percentageReference must be supplied

What it means

stringToBytes (memory-limit.ts:85-94) interprets a numeric input between 0 and 1 (exclusive of 0, inclusive of 1) as a fraction/percentage of a reference total. If no percentageReference is passed, the fraction cannot be converted to bytes and the function throws this error.

Source

Thrown at packages/vitest/src/utils/memory-limit.ts:91

          case 'gib':
            return numericValue * 1024 * 1024 * 1024
        }
      }

      // It ends in some kind of char so we need to do some parsing
    }
    else {
      input = Number.parseFloat(input)
    }
  }

  if (typeof input === 'number') {
    if (input <= 1 && input > 0) {
      if (percentageReference) {
        return Math.floor(input * percentageReference)
      }
      else {
        throw new Error(
          'For a percentage based memory limit a percentageReference must be supplied',
        )
      }
    }
    else if (input > 1) {
      return Math.floor(input)
    }
    else {
      throw new Error('Unexpected numerical input for "memoryLimit"')
    }
  }

  return null
}

View on GitHub (pinned to d568f8ce37)

Solutions

Pass a percentageReference (e.g. total bytes from os.totalmem()) whenever the input may be fractional or '%'-based.
If configuring vmMemoryLimit, use an absolute value (e.g. '1GB', 1073741824) instead of a percentage.
If you are calling stringToBytes directly, always provide the second argument for percentage inputs.

Example fix

// before: fraction without reference
const bytes = stringToBytes('50%')

// after: supply reference, or use absolute
const bytes = stringToBytes('50%', os.totalmem())
// or
const bytes = stringToBytes('1GB')

Defensive patterns

Strategy: validation

Validate before calling

function validateMemoryLimitInput(input: string | number, percentageReference?: number) {
  const numeric = typeof input === 'string' ? Number.parseFloat(input.replace(/[^0-9.-]/g, '')) : input
  if (typeof numeric === 'number' && numeric > 0 && numeric <= 1 && !percentageReference) {
    throw new Error('A percentageReference (e.g. os.totalmem()) is required for fractional/percentage limits')
  }
}

Prevention

Always pass os.totalmem() as percentageReference when inputs may be '%'.
Prefer absolute vmMemoryLimit values ('1GB', bytes) to avoid ambiguity.
Validate user-supplied memory strings before they reach stringToBytes.

When it happens

Trigger: Calling stringToBytes with a fractional value (e.g. 0.25) derived from a '%' string or a raw number, without supplying the second percentageReference argument. Internally, '%' inputs are divided by 100 into a fraction then routed to this branch.

Common situations: A vmMemoryLimit value like '50%' reaching stringToBytes without a reference (caller bug), or a custom caller of stringToBytes passing 0.5 directly. The public config path normally supplies total system memory as the reference, so hitting this usually means an internal caller forgot the argument.

Related errors

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/7f1e8b2f7c0e1ef8.json. Report an issue: GitHub.