SeleniumHQ/selenium · error · Error

ReferenceContext must be string. Received:'${id}'

Error message

ReferenceContext must be string. Received:'${id}'

What it means

Thrown by `CreateContextParameters.referenceContext()` when the argument is not a string (`typeof id !== 'string'`). The reference context id must be the string id of an existing browsing context.

Source

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

// specific language governing permissions and limitations
// under the License.

/**
 * Represents a set of parameters for creating a context.
 * Described in https://w3c.github.io/webdriver-bidi/#command-browsingContext-create.
 */
class CreateContextParameters {
  #map = new Map()

  /**
   * Sets the reference context.
   * @param {string} id - The ID of the reference context.
   * @returns {CreateContextParameters} - The updated instance of CreateContextParameters for chaining.
   * @throws {Error} - If the provided ID is not a string.
   */
  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

View on GitHub (pinned to aa36b38e69)

Solutions

1. Pass the string browsing-context id returned by a create/open context command
2. Ensure the id variable is a defined string

Example fix

// before
params.referenceContext(driver.getWindowHandle()) // may be non-string in BiDi
// after
params.referenceContext(contextId) // contextId is a string from bidi

if (typeof id === 'string') params.referenceContext(id)

const isContextId = (id) => typeof id === 'string'

When it happens

Trigger: Calling `params.referenceContext(undefined)`, `params.referenceContext(123)`, or passing a window/context object instead of its id string.

Common situations: Passing a context object or numeric id instead of the BiDi context id string; undefined when no parent context was chosen.

Related errors

• UserContext must be string. Received:'${userContext}'
• Type must be an instance of String. Received:'${type}'
• Http method must be a string. Received: '${method})'
• Url must be a string. Received:'${url}'
• Username must be a string. Received:'${username}'

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