{"record":{"id":"5e78d00964dfb0a7","repo":"jackwener/OpenCLI","slug":"command-returned-an-unreadable-browser-payload","errorCode":null,"errorMessage":"${command} returned an unreadable browser payload","messagePattern":"(.+?) returned an unreadable browser payload","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/dribbble/utils.js","lineNumber":69,"sourceCode":"    if (/^\\d+$/.test(target)) return target;\n\n    let url;\n    try {\n        url = new URL(target);\n    } catch {\n        throw new ArgumentError('shot must be a numeric id or dribbble.com/shots URL');\n    }\n    if (!/(^|\\.)dribbble\\.com$/i.test(url.hostname)) {\n        throw new ArgumentError('shot URL must use dribbble.com');\n    }\n    const match = url.pathname.match(/^\\/shots\\/(\\d+)(?:-|\\/|$)/);\n    if (!match) throw new ArgumentError('shot URL must match dribbble.com/shots/<id>');\n    return match[1];\n}\n\nexport function requireRows(payload, command) {\n    if (!payload || typeof payload !== 'object') {\n        throw new CommandExecutionError(`${command} returned an unreadable browser payload`);\n    }\n    if (payload.empty) {\n        throw new EmptyResultError(command, payload.reason || `${command} returned no results`);\n    }\n    if (!payload.ok) {\n        const reason = payload.reason ? `: ${payload.reason}` : '';\n        throw new CommandExecutionError(`${command} selector drift${reason}`);\n    }\n    if (!Array.isArray(payload.rows)) {\n        throw new CommandExecutionError(`${command} returned a malformed rows payload`);\n    }\n    if (payload.rows.length === 0) {\n        throw new EmptyResultError(command, `${command} page loaded but no matching rows were found`);\n    }\n    return payload.rows;\n}\n\nexport function requireRow(payload, command) {","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/dribbble/utils.js#L51-L87","documentation":"requireRows inspects the browser payload produced by a scraping command. If the payload is null/undefined or not a plain object, the library cannot even interpret the result and throws this CommandExecutionError. It signals an internal/browser failure rather than bad user input — the page automation did not return a usable result object.","triggerScenarios":"The headless browser command crashed or returned null/undefined; a custom/patched command returned a non-object (string, array at top level); the browser context was destroyed before the payload was serialized.","commonSituations":"Browser (Puppeteer/Playwright-style) not installed or failing to launch, page navigation failing so the command returns nothing, or running an outdated command script whose return shape changed.","solutions":["Re-run the command — a transient browser crash can produce an empty payload.","Verify the browser automation dependency is installed and launches correctly (check its version and logs).","Update the library/command scripts; an older payload shape may no longer match what requireRows expects."],"exampleFix":"// before\nconst rows = cli.rows('shots', payload); // payload is null after a crash\n\n// after\nlet rows;\ntry {\n  rows = cli.rows('shots', payload);\n} catch (e) {\n  payload = await rerunBrowserCommand('shots');\n  rows = cli.rows('shots', payload);\n}","handlingStrategy":"retry","validationCode":"if (payload == null || typeof payload !== 'object' || Array.isArray(payload)) {\n  throw new Error('browser command must return an object payload before requireRows');\n}","typeGuard":"function isBrowserPayload(p) {\n  return p != null && typeof p === 'object' && !Array.isArray(p) && ('ok' in p || 'empty' in p || 'rows' in p);\n}","tryCatchPattern":"try {\n  rows = requireRows(payload, 'shots');\n} catch (e) {\n  if (e instanceof CommandExecutionError && /unreadable browser payload/.test(e.message)) {\n    payload = await rerunBrowserCommand('shots'); // transient browser crash: retry once\n    rows = requireRows(payload, 'shots');\n  } else throw e;\n}","preventionTips":["Keep the browser automation dependency up to date and verify it launches in CI.","Log the raw payload on failure so null vs wrong-shape causes are distinguishable.","Retry browser commands once on empty payloads before giving up."],"tags":["browser-automation","payload","internal-error","scraping"],"backgroundTag":"malformed-payload","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}