microsoft/playwright · error · ValidationError

${path}: expected guid for ${names.toString()}

Error message

${path}: expected guid for ${names.toString()}

What it means

ValidationError raised in _tChannelImplFromWire when the argument for a channel parameter is not an object containing a string guid. The wire format requires { guid: string }; anything else — a primitive, null, an array, or an object whose guid is missing/non-string — falls through to this error before any lookup. It signals malformed input rather than a missing or wrong object.

Source

Thrown at packages/playwright-core/src/server/dispatchers/dispatcher.ts:253

  private _validatorFromWireContext(): ValidatorContext {
    return {
      tChannelImpl: this._tChannelImplFromWire.bind(this),
      binary: this._isInProcess ? 'buffer' : 'fromBase64',
      isUnderTest,
    };
  }

  private _tChannelImplFromWire(names: '*' | string[], arg: any, path: string, context: ValidatorContext): any {
    if (arg && typeof arg === 'object' && typeof arg.guid === 'string') {
      const guid = arg.guid;
      const dispatcher = this._dispatcherByGuid.get(guid);
      if (!dispatcher)
        throw new ValidationError(`${path}: no object with guid ${guid}`);
      if (names !== '*' && !names.includes(dispatcher._type))
        throw new ValidationError(`${path}: object with guid ${guid} has type ${dispatcher._type}, expected ${names.toString()}`);
      return dispatcher;
    }
    throw new ValidationError(`${path}: expected guid for ${names.toString()}`);
  }

  private _tChannelImplToWire(names: '*' | string[], arg: any, path: string, context: ValidatorContext): any {
    if (arg instanceof Dispatcher)  {
      if (names !== '*' && !names.includes(arg._type))
        throw new ValidationError(`${path}: dispatcher with guid ${arg._guid} has type ${arg._type}, expected ${names.toString()}`);
      return { guid: arg._guid };
    }
    throw new ValidationError(`${path}: expected dispatcher ${names.toString()}`);
  }

  existingDispatcher<DispatcherType>(object: any): DispatcherType | undefined {
    return this._dispatcherByObject.get(object) as DispatcherType | undefined;
  }

  registerDispatcher(dispatcher: DispatcherScope) {
    assert(!this._dispatcherByGuid.has(dispatcher._guid));
    this._dispatcherByGuid.set(dispatcher._guid, dispatcher);

View on GitHub (pinned to c8fc3bf8d3)

Solutions

1. Ensure every channel argument is an actual handle object obtained from a prior RPC on the same connection.
2. Add a pre-send assertion: assert(arg && typeof arg === 'object' && typeof arg.guid === 'string').
3. Use the typed client API rather than building raw protocol messages.

Example fix

// before: undefined handle sent as channel arg
await connection.send('page', 'close', { page }); // page is undefined

// after: assign before use
const page = await browser.newPage();
await connection.send('page', 'close', { page });

function isValidWireHandle(arg: any): boolean {
  return !!arg && typeof arg === 'object' && typeof arg.guid === 'string' && arg.guid.length > 0;
}

function isWireHandle(arg: any): arg is { guid: string } {
  return !!arg && typeof arg === 'object' && typeof arg.guid === 'string';
}

When it happens

Trigger: Sending null/undefined/''/0 for a channel parameter, an object without a guid field, or an object whose guid is a number/boolean. Happens in hand-rolled serializers, buggy proxy code, or when a handle variable is undefined due to a missing await.

Common situations: A handle variable that was never assigned (e.g. const page; then used before newPage resolved), JSON that stripped the guid, or custom marshalling that loses the field.

Related errors

• ${path}: no object with guid ${guid}
• ${path}: object with guid ${guid} has type ${dispatcher._typ
• ${path}: expected dispatcher ${names.toString()}
• ${path}: expected channel ${names.toString()}
• Object with guid ${arg.guid} was not bound in the connection

AI-assisted analysis of microsoft/playwright@c8fc3bf8d3 (2026-08-12). Data as JSON: /api/errors/bb784e9e32e50a28. Report an issue: GitHub.