SeleniumHQ/selenium · error · Error

Background must be boolean. Received:'${background}'

Error message

Background must be boolean. Received:'${background}'

What it means

Thrown by `CreateContextParameters.background()` when the argument is not a boolean (`typeof background !== 'boolean'`). This is a strict boolean check, so truthy/falsy values like 0, 1, and 'true' are all rejected — only literal `true`/`false` pass.

Source

Thrown at javascript/selenium-webdriver/bidi/createContextParameters.js:48

   */
  referenceContext(id) {
    if (typeof id !== 'string') {
      throw new Error(`ReferenceContext must be string. Received:'${id}'`)
    }
    this.#map.set('referenceContext', id)
    return this
  }

  /**
   * Sets the background parameter.
   *
   * @param {boolean} background - The background value to set.
   * @returns {CreateContextParameters} - The updated instance of CreateContextParameters for chaining.
   * @throws {Error} - If the background parameter is not a boolean.
   */
  background(background) {
    if (typeof background !== 'boolean') {
      throw new Error(`Background must be boolean. Received:'${background}'`)
    }
    this.#map.set('background', background)
    return this
  }

  /**
   * Sets the user context.
   * @param {string} userContext - The user context to set.
   * @returns {CreateContextParameters} - The updated instance of CreateContextParameters for chaining.
   * @throws {Error} - If the userContext parameter is not a string.
   */
  userContext(userContext) {
    if (typeof userContext !== 'string') {
      throw new Error(`UserContext must be string. Received:'${userContext}'`)
    }
    this.#map.set('userContext', userContext)
    return this
  }

View on GitHub (pinned to aa36b38e69)

Solutions

1. Pass a literal `true` or `false`
2. If sourced from config, convert explicitly: `String(val).toLowerCase() === 'true'`

Example fix

// before
params.background('true')
// after
params.background(true)

if (typeof bg === 'boolean') params.background(bg)

const isBoolean = (v) => typeof v === 'boolean'

When it happens

Trigger: Calling `params.background(1)`, `params.background('true')`, or `params.background(undefined)`.

Common situations: Boolean sourced from config/env as a string ('true'/'false'); passing a numeric 0/1 from a flag.

Related errors

• ReferenceContext must be string. Received:'${id}'
• UserContext must be string. Received:'${userContext}'
• Pass in a CaptureScreenshotParameters object. Received: ${ca
• ${msg}
• Origin must be one of ${Object.values(Origin)}. Received:'${

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