vitest-dev/vitest · error · Error

For a percentage based memory limit a percentageReference…

Error message

For a percentage based memory limit a percentageReference must be supplied

What it means

stringToBytes converts memory limits. A numeric input in (0, 1] is interpreted as a fraction (e.g. 0.5 = 50%) and requires a percentageReference (the total to take the fraction of). If none is provided it throws. An input > 1 is treated as absolute bytes; a non-positive number throws 'Unexpected numerical input'. This is used to parse vmMemoryLimit.

Solutions

Express the limit with a unit suffix: '50%' or '512MB' instead of a bare 0.5.
If calling stringToBytes directly, always pass percentageReference (e.g. os.totalmem()).
Use an absolute byte value greater than 1 to bypass the percentage branch entirely.
Confirm test.vmMemoryLimit is a string ('50%', '1g') rather than a raw fraction.

Example fix

// before
test: { vmMemoryLimit: 0.5 } // bare fraction, no reference

// after
test: { vmMemoryLimit: '50%' } // or '2g'

Defensive patterns

Strategy: validation

Validate before calling

import * as os from 'node:os'
function resolveLimit(input) {
  if (typeof input === 'number' && input > 0 && input <= 1) {
    return stringToBytes(input, os.totalmem()) // always pass a reference
  }
  return stringToBytes(input)
}

Type guard

function isPercentageValue(v) {
  return typeof v === 'number' && v > 0 && v <= 1
}

Prevention

Express vmMemoryLimit with a unit: '50%', '2g', '512MB'.
When calling stringToBytes with a fraction, always pass percentageReference.
Prefer absolute sizes to avoid the percentage branch.

When it happens

Trigger: Calling stringToBytes with a fractional number like 0.5 without passing percentageReference. In Vitest this path is reached internally when computing worker memory limits from config.vmMemoryLimit; the reference (total system memory) is normally supplied, so seeing this error means an internal caller omitted it or a custom value slipped through as a raw fraction.

Common situations: Setting test.vmMemoryLimit to a bare decimal (e.g. 0.5) in a context where Vitest cannot supply a percentage reference, or a custom integration calling stringToBytes directly without a reference. Most users express limits as percentages via the '%' suffix or as absolute sizes (e.g. '512MB'), which do not hit this branch.

Related errors

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/7f1e8b2f7c0e1ef8. Report an issue: GitHub.

Appendix: 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 1fa9837ec2)