{"record":{"id":"1a28f671b07b8f43","repo":"jackwener/OpenCLI","slug":"google-images-returned-an-unexpected-page-state-pa","errorCode":null,"errorMessage":"google images returned an unexpected page-state payload shape.","messagePattern":"google images returned an unexpected page-state payload shape\\.","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/google/images.js","lineNumber":387,"sourceCode":"            thumbnailUrl,\n            sourceUrl,\n            source,\n            width: Number.isFinite(Number(row[5])) ? Number(row[5]) : null,\n            height: Number.isFinite(Number(row[6])) ? Number(row[6]) : null,\n        };\n    });\n\n    if (rows.length === 0) {\n        throw new EmptyResultError('google images', `No Google image results matched \"${query}\".`);\n    }\n    return rows;\n}\n\nasync function evaluateGoogleImagesPageState(page) {\n    const raw = await page.evaluate(inspectGoogleImagesPage);\n    const state = unwrapBrowserResult(raw);\n    if (!state || typeof state !== 'object' || Array.isArray(state)) {\n        throw new CommandExecutionError('google images returned an unexpected page-state payload shape.');\n    }\n    return state;\n}\n\nasync function evaluateGoogleImageRows(page, limit, resolveOriginal) {\n    let rows = [];\n    for (let attempt = 0; attempt < 6; attempt += 1) {\n        const raw = await page.evaluate(extractGoogleImageRows, limit, resolveOriginal);\n        rows = requireRows(raw, 'google images');\n        if (rows.length > 0) {\n            return rows;\n        }\n        if (attempt < 5) {\n            if (typeof page.scroll === 'function') {\n                await page.scroll('down', 900).catch(() => {});\n            }\n            await page.wait(1).catch(() => {});\n        }","sourceCodeStart":369,"sourceCodeEnd":405,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/google/images.js#L369-L405","documentation":"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.","triggerScenarios":"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.","commonSituations":"EU consent-wall redirect before results render; bot-detection interstitial; browser crash or stale tab; automation-library version mismatch altering evaluate return values.","solutions":["Re-run the command — transient navigation/consent states often clear on retry.","Open the query in a normal browser to check for a CAPTCHA or consent wall; resolve or switch IP/locale.","Verify the headless browser and driver are installed and version-compatible.","Catch CommandExecutionError and retry with backoff or fall back to another image backend."],"exampleFix":"// before\nconst state = unwrapBrowserResult(raw);\nif (!state || typeof state !== 'object' || Array.isArray(state)) {\n  throw new CommandExecutionError('google images returned an unexpected page-state payload shape.');\n}\n// after\nconst state = unwrapBrowserResult(raw);\nif (!state || typeof state !== 'object' || Array.isArray(state)) {\n  await page.reload();           // or wait for consent/CAPTCHA to clear, then re-inspect\n  const retry = unwrapBrowserResult(await page.evaluate(inspectGoogleImagesPage));\n  if (!retry || typeof retry !== 'object' || Array.isArray(retry)) {\n    throw new CommandExecutionError('google images returned an unexpected page-state payload shape.');\n  }\n  return retry;\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":"const isPageState = (s) => !!s && typeof s === 'object' && !Array.isArray(s);","tryCatchPattern":"try {\n  return await run('google images', query);\n} catch (e) {\n  if (/unexpected page-state payload shape/.test(e.message)) {\n    await sleep(3000);\n    return await run('google images', query); // consent/CAPTCHA may have cleared\n  }\n  throw e;\n}","preventionTips":["Handle EU consent walls (pre-set CONSENT cookie or pick another locale).","Add backoff retries for interstitial pages.","Keep the browser automation stack version-matched.","Check for CAPTCHA in a real browser when failures repeat."],"tags":["scraping","google-images","payload-shape","browser"],"backgroundTag":"unexpected-payload-shape","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}