jackwener/OpenCLI · error · CommandExecutionError

Twitter/X ${label} returned a malformed Browser Bridge envel

Error message

Twitter/X ${label} returned a malformed Browser Bridge envelope

What it means

unwrapTwitterEvaluateResult validates the Browser Bridge envelope for Twitter/X evaluate calls. A valid envelope is an object with a string session field and a data property; if the object has session but lacks data (or session is not a string), the wrapper concludes the envelope is malformed and throws CommandExecutionError. This protects callers from consuming corrupted bridge results.

Source

Thrown at clis/twitter/auth.js:20

import { registerSiteAuthCommands } from '../_shared/site-auth.js';
import { normalizeTwitterScreenName } from './shared.js';

const SCREEN_NAME_POLL_SECONDS = 1;
const SCREEN_NAME_POLLS = 8;
const SCREEN_NAME_AGREEMENTS = 3;

async function hasTwitterSessionCookies(page) {
  const cookies = await page.getCookies({ url: 'https://x.com' });
  const names = new Set(cookies.map(cookie => cookie.name));
  return names.has('auth_token') && names.has('ct0');
}

function unwrapTwitterEvaluateResult(value, label) {
  if (value && typeof value === 'object' && !Array.isArray(value) && 'session' in value) {
    if (typeof value.session === 'string' && Object.prototype.hasOwnProperty.call(value, 'data')) {
      return value.data;
    }
    throw new CommandExecutionError(`Twitter/X ${label} returned a malformed Browser Bridge envelope`);
  }
  return value;
}

async function readScreenName(page) {
  const href = unwrapTwitterEvaluateResult(await page.evaluate(`() => {
    const link = document.querySelector('a[data-testid="AppTabBar_Profile_Link"]');
    return link ? link.getAttribute('href') : null;
  }`), 'profile link probe');
  if (href !== null && typeof href !== 'string') {
    throw new CommandExecutionError('Twitter/X profile link probe returned a malformed href');
  }
  return normalizeTwitterScreenName(typeof href === 'string' ? href : '');
}

/**
 * Right after an account switch the home surface keeps showing the previous
 * account for a few seconds, so a single read misreports it (#2252); trust

View on GitHub (pinned to 49907e53dc)

Solutions

Reload the browser and the extension so the bridge restarts with the current envelope format.
Verify the Browser Bridge extension version matches what the CLI expects; update whichever is stale.
Re-run the command; transient bridge races can produce partial envelopes.
Capture the raw evaluate value to confirm the envelope shape before reporting a bug.

Example fix

// before
const value = await page.evaluate('() => location.href');
// after
const value = unwrapTwitterEvaluateResult(await page.evaluate('() => location.href'), 'href probe');
if (typeof value !== 'string') throw new Error('Unexpected href probe result');

Defensive patterns

Strategy: type-guard

Type guard

function isBridgeEnvelope(v) {
  return v !== null && typeof v === 'object' && !Array.isArray(v) && 'session' in v;
}
function isWellFormedEnvelope(v) {
  return !isBridgeEnvelope(v) || (typeof v.session === 'string' && 'data' in v);
}

Try / catch

try {
  const data = unwrapTwitterEvaluateResult(await page.evaluate(src), 'probe');
} catch (e) {
  if (/malformed Browser Bridge envelope/.test(e.message)) {
    await reloadExtension();
    return retry();
  }
  throw e;
}

Prevention

Restart browser/extension after any CLI or extension upgrade
Pin matching CLI + extension versions
Avoid running multiple extension versions in one profile
Retry once — transient bridge races can emit partial envelopes

When it happens

Trigger: page.evaluate (via unwrapTwitterEvaluateResult, e.g. from readScreenName's href call) returned an object containing a session key but no data key, or session is not a string.

Common situations: Browser Bridge extension upgraded or downgraded to a version with a different envelope format; multiple extension versions installed; bridge returning an error object that coincidentally includes a session field.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/0b3d3f6caac81d6d. Report an issue: GitHub.