jackwener/OpenCLI · error · CommandExecutionError

Browser session required for twitter unblock

Error message

Browser session required for twitter unblock

What it means

CommandExecutionError (code COMMAND_EXEC) thrown by `twitter unblock` because the command is a browser-write command: it requires an interactive Playwright/CDP page attached to the logged-in X session. When `page` is null the library refuses to attempt the write via the API-only path. It fails fast rather than silently doing nothing.

Source

Thrown at clis/twitter/unblock.js:17

import { CommandExecutionError, TimeoutError } from '@jackwener/opencli/errors';
import { cli, Strategy } from '@jackwener/opencli/registry';
cli({
    site: 'twitter',
    name: 'unblock',
    access: 'write',
    description: 'Unblock a Twitter user',
    domain: 'x.com',
    strategy: Strategy.UI,
    browser: true,
    args: [
        { name: 'username', type: 'string', positional: true, required: true, help: 'Twitter screen name (without @)' },
    ],
    columns: ['status', 'message'],
    func: async (page, kwargs) => {
        if (!page)
            throw new CommandExecutionError('Browser session required for twitter unblock');
        const username = kwargs.username.replace(/^@/, '');
        await page.goto(`https://x.com/${username}`);
        await page.wait({ selector: '[data-testid="primaryColumn"]' });
        const result = await page.evaluate(`(async () => {
        let writeStarted = false;
        try {
            let attempts = 0;
            let unblockBtn = null;
            const getPrimary = () => document.querySelector('[data-testid="primaryColumn"]');
            if (!getPrimary()) {
                return { ok: false, message: 'Could not find profile surface. Are you logged in?' };
            }

            while (attempts < 20) {
                const primary = getPrimary();
                if (!primary) {
                    return { ok: false, message: 'Could not find profile surface. Are you logged in?' };
                }

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Start/connect a browser session first (the CLI's browser login/connect flow for x.com) and ensure you are logged in, then re-run `twitter unblock`
  2. Run the command in interactive mode rather than a mode that passes no page
  3. In scripts, check browser availability before invoking the command and fail with a clear message

Example fix

// before
await cli.run(['twitter', 'unblock', 'user']); // no browser session
// after
const page = await getBrowserPage('x.com'); // connect logged-in session first
if (!page) throw new Error('Start a browser session and log in to x.com first');
await cli.run(['twitter', 'unblock', 'user']);
Defensive patterns

Strategy: validation

Validate before calling

if (!browserSession || !browserSession.page) {
  throw new Error('Start a browser session and log in to x.com before running twitter write commands');
}

Type guard

function hasBrowserPage(ctx) { return ctx != null && typeof ctx.page === 'object' && ctx.page !== null; }

Try / catch

try {
  await cli.run(['twitter', 'unblock', user]);
} catch (e) {
  if (e.code === 'COMMAND_EXEC' && /Browser session required/.test(e.message)) {
    console.error('Connect a browser session and log in to x.com first');
  } else throw e;
}

Prevention

When it happens

Trigger: Running `twitter unblock <username>` without an active browser session (e.g. headless/API mode, or before connecting a Chrome session), so `func` receives page === null/undefined.

Common situations: Scripting the CLI without launching/connecting the browser; running in CI where no logged-in Chrome exists; forgetting the login/bootstrap step for x.com in the current profile.

Related errors

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