SeleniumHQ/selenium · error · Error

Reason phrase must be a string. Received: '${reasonPhrase})'

Error message

Reason phrase must be a string. Received: '${reasonPhrase})'

What it means

Thrown by ProvideResponseParameters.reasonPhrase() when the reasonPhrase argument is not a string (typeof !== 'string'). The BiDi response requires the reason phrase (e.g. 'OK', 'Not Found') as a string, so numbers, null, or objects are rejected before serialization.

Source

Thrown at javascript/selenium-webdriver/bidi/provideResponseParameters.js:96

        throw new Error(`Header must be an instance of Header. Received:'${header}'`)
      }
      headerList.push(Object.fromEntries(header.asMap()))
    })

    this.#map.set('headers', headerList)
    return this
  }

  /**
   * Sets the reason phrase for the response.
   *
   * @param {string} reasonPhrase - The reason phrase to set.
   * @returns {ProvideResponseParameters} - Returns the ProvideResponseParameters object for chaining.
   * @throws {Error} - If the reason phrase is not a string.
   */
  reasonPhrase(reasonPhrase) {
    if (typeof reasonPhrase !== 'string') {
      throw new Error(`Reason phrase must be a string. Received: '${reasonPhrase})'`)
    }
    this.#map.set('reasonPhrase', reasonPhrase)
    return this
  }

  /**
   * Sets the status code for the response.
   *
   * @param {number} statusCode - The status code to set.
   * @returns {ProvideResponseParameters} - Returns the ProvideResponseParameters object for chaining.
   * @throws {Error} - If the status code is not an integer.
   */
  statusCode(statusCode) {
    if (!Number.isInteger(statusCode)) {
      throw new Error(`Status must be an integer. Received:'${statusCode}'`)
    }

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

View on GitHub (pinned to aa36b38e69)

Solutions

1. Pass a string reason phrase, e.g. params.reasonPhrase('OK') or params.reasonPhrase('Not Found').
2. If the value is dynamic, coerce with String(reasonPhrase) only when you are sure it is textually valid.
3. Omit the reasonPhrase() call entirely if you do not need to set it.

Example fix

// before
const params = new ProvideResponseParameters(id).reasonPhrase(200)

// after
const params = new ProvideResponseParameters(id).reasonPhrase('OK')

if (typeof reasonPhrase !== 'string') {
  throw new TypeError('reasonPhrase must be a string')
}

function isString(v) {
  return typeof v === 'string'
}

When it happens

Trigger: Calling params.reasonPhrase(200) (passing a status code by mistake), params.reasonPhrase(null), params.reasonPhrase(undefined), or params.reasonPhrase({text:'OK'}).

Common situations: Confusing the reason phrase with the numeric status code; passing an undefined variable because the reason string was never set; reading the phrase from a typed field that returned a number.

Related errors

• Params must be an instance of ProvideResponseParameters. Rec
• Value must be an instance of BytesValue. Received: ${typeof
• CookieHeader must be an instance of Header. Received:'${head
• Header must be an instance of Header. Received:'${header}'
• Status must be an integer. Received:'${statusCode}'

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