SeleniumHQ/selenium · error · Error

Quality must be a number. Received:'${quality}'

Error message

Quality must be a number. Received:'${quality}'

What it means

CaptureScreenshotParameters.imageFormat() optionally accepts a quality number as its second argument. When quality is not undefined, it validates typeof quality === 'number'. Passing a string (e.g. '80'), a boolean, null, an object, or NaN-equivalent fails the check. Quality is meaningful only for lossy formats (jpeg); it represents compression quality, conventionally 0–100.

Source

Thrown at javascript/selenium-webdriver/bidi/captureScreenshotParameters.js:69

  /**
   * Sets the image format and quality for capturing a screenshot.
   *
   * @param {string} type - The image format type.
   * @param {number} [quality] - The image quality (optional).
   * @throws {Error} If the type is not a string or if the quality is not a number.
   * @returns {CaptureScreenshotParameters} - The current instance of the CaptureScreenshotParameters for chaining.
   */
  imageFormat(type, quality = undefined) {
    if (typeof type !== 'string') {
      throw new Error(`Type must be an instance of String. Received:'${type}'`)
    }

    this.#map.set('type', type)

    if (quality !== undefined) {
      if (typeof quality !== 'number') {
        throw new Error(`Quality must be a number. Received:'${quality}'`)
      }
      this.#map.set('quality', quality)
    }
    return this
  }

  /**
   * Sets the clip rectangle for capturing a screenshot.
   *
   * @param {BoxClipRectangle|ElementClipRectangle} clipRectangle - The clip rectangle to set.
   * @throws {Error} If the clipRectangle is not an instance of ClipRectangle.
   * @returns {CaptureScreenshotParameters} - The current instance of the CaptureScreenshotParameters for chaining.
   */
  clipRectangle(clipRectangle) {
    if (!(clipRectangle instanceof BoxClipRectangle || clipRectangle instanceof ElementClipRectangle)) {
      throw new Error(`ClipRectangle must be an instance of ClipRectangle. Received:'${clipRectangle}'`)
    }
    this.#map.set('clip', Object.fromEntries(clipRectangle.asMap()))

View on GitHub (pinned to aa36b38e69)

Solutions

1. Pass a primitive number for quality, or omit it entirely: imageFormat('jpeg', 80) or imageFormat('png').
2. Convert string config values with Number() and verify isFinite() before passing.
3. Use undefined (omit) rather than null when you want the default.
4. Keep quality within [0,100] to avoid downstream server rejection.

Example fix

// before
params.imageFormat('jpeg', '80')

// after
params.imageFormat('jpeg', Number(qualityStr))

if (quality !== undefined && (typeof quality !== 'number' || !isFinite(quality))) {
  throw new TypeError('imageFormat quality must be a finite number')
}

function isValidQuality(q) {
  return q === undefined || (typeof q === 'number' && isFinite(q))
}

When it happens

Trigger: Calling imageFormat('jpeg', '80') with a string quality. Passing null as quality (null is not undefined, typeof 'object'). Passing a boolean. Passing quality from config as a string. Passing NaN.

Common situations: Config/CLI values arriving as strings (e.g. env vars, JSON parsed loosely). Forgetting to Number()-convert. Passing null to mean 'default' instead of omitting the argument.

Related errors

• Type must be an instance of String. Received:'${type}'
• Origin must be one of ${Object.values(Origin)}. Received:'${
• ClipRectangle must be an instance of ClipRectangle. Received
• Pass in a CaptureScreenshotParameters object. Received: ${ca
• ${msg}

AI-assisted analysis of SeleniumHQ/selenium@aa36b38e69 (2026-08-14). Data as JSON: /api/errors/37faf70ffa865fd8. Report an issue: GitHub.