jackwener/OpenCLI · error · AuthRequiredError

Xiaohongshu search results are blocked behind a login wall

Error message

Xiaohongshu search results are blocked behind a login wall

What it means

collectSearchHarvest throws this AuthRequiredError when the page-wait script returns 'login_wall', meaning www.xiaohongshu.com redirected or rendered its login gate instead of search results. The library surfaces this as an authentication requirement rather than a generic failure so callers can re-authenticate. It is the library's structured signal that anonymous search is no longer permitted for this session.

Source

Thrown at clis/xiaohongshu/search.js:789

            scrollHeight: metrics.scrollHeight,
            clientHeight: metrics.clientHeight,
            cardCount,
            feedClientHeight: feedContainer ? feedContainer.clientHeight : null,
            distinctCardTops: distinctCardTops.size,
            rounds: round,
            stopReason,
            elapsedMs,
            securityBlock,
          },
        };
      })()
    `;
}

async function collectSearchHarvest(page, limit, requestedFilters) {
    const waitResult = unwrapEvaluateResult(await page.evaluate(WAIT_FOR_CONTENT_JS));
    if (waitResult === 'login_wall') {
        throw new AuthRequiredError('www.xiaohongshu.com', 'Xiaohongshu search results are blocked behind a login wall');
    }
    if (waitResult === 'security_block') {
        throw new CliError('SECURITY_BLOCK', 'Xiaohongshu search was blocked by request-frequency or security controls.', 'Wait before retrying or use a different logged-in browser session.');
    }
    if (waitResult === 'timeout') {
        throw new TimeoutError('xiaohongshu search content', CONTENT_WAIT_SECONDS);
    }
    if (waitResult !== 'content') {
        throw new CommandExecutionError('Unexpected Xiaohongshu search wait payload shape.');
    }
    requireFilterApplication(await page.evaluate(buildApplySearchFiltersJs(requestedFilters)));
    const harvestOptions = harvestOptionsForLimit(limit);
    const harvest = requireHarvestPayload(await page.evaluate(buildScrollHarvestJs('www.xiaohongshu.com', limit, harvestOptions)), 'www.xiaohongshu.com');
    if (harvest.diag.securityBlock) {
        throw new CliError('SECURITY_BLOCK', 'Xiaohongshu search was blocked by request-frequency or security controls.', 'Wait before retrying or use a different logged-in browser session.');
    }
    return harvest;
}

View on GitHub (pinned to 49907e53dc)

Solutions

Log into www.xiaohongshu.com in the automation browser profile and rerun the command.
Connect the CLI to an existing browser profile that already has an authenticated session (e.g. launch with your regular user data dir).
Refresh/restore session cookies and retry.
Catch AuthRequiredError and pause the crawl until manual login is done.
Switch to a residential IP or different network if datacenter IPs trigger forced login.

Example fix

// before
const notes = await xhs.search('coffee');
// after
try {
  const notes = await xhs.search('coffee');
} catch (e) {
  if (e.name === 'AuthRequiredError' && /login wall/.test(e.message)) {
    await xhs.openLoginPage(); // prompt user to log in, then retry
    const notes = await xhs.search('coffee');
  } else throw e;
}

Defensive patterns

Strategy: try-catch

Validate before calling

const loggedIn = await page.evaluate(() =>
  Boolean(document.cookie.includes('web_session') || window.__INITIAL_STATE__?.user?.loggedIn));
if (!loggedIn) throw new Error('xiaohongshu login required before search');

Type guard

function isAuthRequiredError(e) {
  return e instanceof Error && (e.name === 'AuthRequiredError' || /login wall/i.test(e.message));
}

Try / catch

try {
  const notes = await xhs.search(query);
} catch (e) {
  if (isAuthRequiredError(e)) {
    await promptUserLogin('www.xiaohongshu.com');
    return xhs.search(query);
  }
  throw e;
}

Prevention

Use a persistent browser profile that stays logged in.
Check session validity before starting long crawls.
Handle AuthRequiredError explicitly and pause instead of retrying blindly.
Avoid fresh headless profiles for anonymous search — login walls are common.
Refresh cookies proactively during long-running jobs.

When it happens

Trigger: Running the search command in a browser context without a logged-in xiaohongshu.com session when the site enforces login for search; a session cookie expiring mid-crawl; the site deciding this client must log in before showing results.

Common situations: Fresh automation profile with no cookies; cookies cleared or expired after inactivity; xiaohongshu tightening anonymous-access policy; datacenter IP ranges triggering forced login; a previously working session hitting a 401/login redirect.

Related errors

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