jackwener/OpenCLI · error · CommandExecutionError

google images returned an unexpected page-state payload shap

Error message

google images returned an unexpected page-state payload shape.

What it means

In `evaluateGoogleImagesPageState`, the in-page `inspectGoogleImagesPage` script must return a plain object describing the page state. This guard throws a CommandExecutionError when `unwrapBrowserResult(raw)` yields null, a non-object, or an array — i.e. the page-state inspection did not return the expected payload, usually because the page isn't a Google Images results page (CAPTCHA, consent screen, redirect) or the evaluation failed.

Source

Thrown at clis/google/images.js:387

            thumbnailUrl,
            sourceUrl,
            source,
            width: Number.isFinite(Number(row[5])) ? Number(row[5]) : null,
            height: Number.isFinite(Number(row[6])) ? Number(row[6]) : null,
        };
    });

    if (rows.length === 0) {
        throw new EmptyResultError('google images', `No Google image results matched "${query}".`);
    }
    return rows;
}

async function evaluateGoogleImagesPageState(page) {
    const raw = await page.evaluate(inspectGoogleImagesPage);
    const state = unwrapBrowserResult(raw);
    if (!state || typeof state !== 'object' || Array.isArray(state)) {
        throw new CommandExecutionError('google images returned an unexpected page-state payload shape.');
    }
    return state;
}

async function evaluateGoogleImageRows(page, limit, resolveOriginal) {
    let rows = [];
    for (let attempt = 0; attempt < 6; attempt += 1) {
        const raw = await page.evaluate(extractGoogleImageRows, limit, resolveOriginal);
        rows = requireRows(raw, 'google images');
        if (rows.length > 0) {
            return rows;
        }
        if (attempt < 5) {
            if (typeof page.scroll === 'function') {
                await page.scroll('down', 900).catch(() => {});
            }
            await page.wait(1).catch(() => {});
        }

View on GitHub (pinned to 49907e53dc)

Solutions

1. Re-run the command — transient navigation/consent states often clear on retry.
2. Open the query in a normal browser to check for a CAPTCHA or consent wall; resolve or switch IP/locale.
3. Verify the headless browser and driver are installed and version-compatible.
4. Catch CommandExecutionError and retry with backoff or fall back to another image backend.

Example fix

// before
const state = unwrapBrowserResult(raw);
if (!state || typeof state !== 'object' || Array.isArray(state)) {
  throw new CommandExecutionError('google images returned an unexpected page-state payload shape.');
}
// after
const state = unwrapBrowserResult(raw);
if (!state || typeof state !== 'object' || Array.isArray(state)) {
  await page.reload();           // or wait for consent/CAPTCHA to clear, then re-inspect
  const retry = unwrapBrowserResult(await page.evaluate(inspectGoogleImagesPage));
  if (!retry || typeof retry !== 'object' || Array.isArray(retry)) {
    throw new CommandExecutionError('google images returned an unexpected page-state payload shape.');
  }
  return retry;
}

const isPageState = (s) => !!s && typeof s === 'object' && !Array.isArray(s);

try {
  return await run('google images', query);
} catch (e) {
  if (/unexpected page-state payload shape/.test(e.message)) {
    await sleep(3000);
    return await run('google images', query); // consent/CAPTCHA may have cleared
  }
  throw e;
}

When it happens

Trigger: Calling `google images <query>` where `page.evaluate(inspectGoogleImagesPage)` returns null/undefined/an array: navigation landed on a consent or CAPTCHA page, the tab navigated away mid-evaluation, or the browser driver returned an unexpected serialization.

Common situations: EU consent-wall redirect before results render; bot-detection interstitial; browser crash or stale tab; automation-library version mismatch altering evaluate return values.

Related errors

• Google Scholar search returned an unexpected payload shape
• google images returned an unexpected row shape.
• Barchart greeks returned an unreadable options payload
• Douyin search extraction failed: ${error instanceof Error ?
• No profile found for: ${author}

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