{"record":{"id":"68a20c339d0e0ca1","repo":"jackwener/OpenCLI","slug":"amazon-action-hit-a-robot-check","errorCode":null,"errorMessage":"amazon ${action} hit a robot check","messagePattern":"amazon (.+?) hit a robot check","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/amazon/shared.js","lineNumber":395,"sourceCode":"    try {\n        await page.goto(url, { settleMs });\n        await page.wait(1.5);\n        return await readPageState(page);\n    }\n    catch (error) {\n        const message = error instanceof Error ? error.message : String(error);\n        if (message.includes('Inspected target navigated or closed')\n            || message.includes('Cannot find context with specified id')\n            || message.includes('Target closed')) {\n            throw new CommandExecutionError(`amazon ${action} navigation lost the current browser target`, `${buildChallengeHint(action)} If CDP is attached to a stale tab, open a fresh Amazon tab and retry.`);\n        }\n        throw error;\n    }\n}\nexport function assertUsableState(state, action) {\n    if (!isRobotState(state))\n        return;\n    throw new CommandExecutionError(`amazon ${action} hit a robot check`, buildChallengeHint(action));\n}\nexport const __test__ = {\n    buildSearchUrl,\n    extractAsin,\n    amazonHostFromInput,\n    buildProductUrl,\n    buildDiscussionUrl,\n    normalizeProductUrl,\n    canonicalizeAmazonUrl,\n    resolveBestsellersUrl,\n    resolveRankingUrl,\n    isSupportedRankingPath,\n    isRankingPaginationUrl,\n    extractCategoryNodeId,\n    parsePriceText,\n    parseRatingValue,\n    parseReviewCount,\n    extractReviewCountFromCardText,","sourceCodeStart":377,"sourceCodeEnd":413,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/amazon/shared.js#L377-L413","documentation":"A CommandExecutionError thrown by assertUsableState when the loaded Amazon page state matches the robot-check pattern (isRobotState). Amazon served a CAPTCHA/verify page instead of real content, so the library aborts with a challenge hint rather than returning garbage or empty data. It is detected in every read path: search, product, discussion, offers, and rankings.","triggerScenarios":"Any amazon read command (search/product/discussion/offer/rankings) where the rendered page contains Amazon's bot-detection interstitial — typically triggered by datacenter IPs, high request rates, missing cookies, or headless browser fingerprints.","commonSituations":"Running automation from AWS/GitHub Actions/CI IPs; scraping too many pages per minute; reusing a session that already tripped a challenge; headless Chrome fingerprint detection; regional blocks.","solutions":["Solve the robot check manually in the attached Chrome tab, then retry","Switch to a residential IP or different network/proxy","Slow down request rate and add delays between commands","Reuse a logged-in browser session with real cookies instead of a clean headless profile"],"exampleFix":"// before\nfor (const asin of asins) await amazonProduct(asin); // rapid-fire\n// after\nfor (const asin of asins) {\n  await amazonProduct(asin);\n  await new Promise((r) => setTimeout(r, 5000));\n}","handlingStrategy":"retry","validationCode":"// pre-check the page before parsing:\nconst html = await page.content();\nif (/captcha|Enter the characters you see below/i.test(html)) throw new Error('robot check present — solve it manually first');","typeGuard":null,"tryCatchPattern":"try {\n  const data = await amazonSearch({ query });\n} catch (err) {\n  if (err.message.includes('hit a robot check')) {\n    await sleep(30000);          // back off\n    // or pause and let a human solve the CAPTCHA in the attached tab\n    return amazonSearch({ query });\n  } else throw err;\n}","preventionTips":["Run from residential IPs, not datacenter/CI","Throttle request rate with delays between commands","Reuse a logged-in session with real cookies","Solve any CAPTCHA in the attached Chrome tab promptly","Rotate proxies if volume is high"],"tags":["robot-check","captcha","rate-limiting","scraping"],"backgroundTag":"robot-check-detected","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}