jackwener/OpenCLI · error · AuthRequiredError

auth

Error message

auth

What it means

verifyZsxqIdentity probes the zsxq.com /v2/users/self endpoint using the browser session; when the probe detects an authentication problem (typically a 401 or login redirect) it throws AuthRequiredError('zsxq.com', detail). This is the library's way of signaling that the user's zsxq cookie/session is missing or no longer valid before any authenticated command can proceed.

Source

Thrown at clis/zsxq/auth.js:36

          credentials: 'include',
          headers: { Accept: 'application/json' },
        });
        if (r.status === 401 || r.status === 403) {
          return { kind: 'auth', detail: 'zsxq /v2/users/self returned HTTP ' + r.status };
        }
        if (!r.ok) return { kind: 'http', httpStatus: r.status };
        const d = await r.json();
        if (d?.succeeded === false || !d?.resp_data?.user) {
          return { kind: 'auth', detail: 'zsxq /v2/users/self returned succeeded=false — anonymous' };
        }
        const u = d.resp_data.user;
        return { ok: true, user_id: String(u.user_id || u.id || ''), name: String(u.name || u.nickname || '') };
      } catch (e) {
        return { kind: 'exception', detail: String(e && e.message || e) };
      }
    })()
  `);
  if (probe?.kind === 'auth') throw new AuthRequiredError('zsxq.com', probe.detail);
  if (probe?.kind === 'http') throw new CommandExecutionError(`HTTP ${probe.httpStatus} from zsxq /v2/users/self`);
  if (probe?.kind === 'exception') throw new CommandExecutionError(`zsxq whoami failed: ${probe.detail}`);
  if (!probe?.ok) throw new CommandExecutionError(`Unexpected zsxq probe: ${JSON.stringify(probe)}`);
  if (!probe.user_id) {
    throw new AuthRequiredError('zsxq.com', 'zsxq /v2/users/self 200 but user_id missing — incomplete session');
  }
  return { user_id: probe.user_id, name: probe.name };
}

registerSiteAuthCommands({
  site: 'zsxq',
  domain: 'zsxq.com',
  loginUrl: 'https://wx.zsxq.com/login',
  columns: ['user_id', 'name'],
  verify: verifyZsxqIdentity,
  // No-navigation poll: probe the API from the current page so the login-page
  // QR code isn't reset by a goto on every interval.
  poll: async (page) => {

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Run the library's zsxq login flow (registerSiteAuthCommands 'zsxq' wait-for-login) to establish a valid session, then retry.
  2. Verify the browser profile used actually contains zsxq.com cookies (visit zsxq.com manually and confirm you are logged in).
  3. Clear and re-create the browser session/profile if stale cookies cause repeated auth rejection.
  4. Check probe.detail in the error message for the specific auth failure reason (e.g. 401 body) and address accordingly.

Example fix

// before
const identity = await verifyZsxqIdentity(page);
// after
try {
  const identity = await verifyZsxqIdentity(page);
} catch (e) {
  if (e instanceof AuthRequiredError) {
    await performZsxqLogin(page); // interactive login flow
    return verifyZsxqIdentity(page);
  }
  throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

// before calling commands, probe login state
const r = await page.request.get('https://api.zsxq.com/v2/users/self');
if (r.status() === 401) await runZsxqLogin(page);

Type guard

const isAuthRequired = (e) => e instanceof AuthRequiredError || e?.name === 'AuthRequiredError';

Try / catch

try {
  const identity = await verifyZsxqIdentity(page);
} catch (e) {
  if (isAuthRequired(e)) {
    await loginZsxq(page);
    return verifyZsxqIdentity(page);
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling any zsxq command that requires identity verification while the browser session lacks valid zsxq.com login cookies, or after cookies expired / were cleared, so /v2/users/self responds with an auth-rejecting status.

Common situations: Developers running headless browser automation after session expiry; machine without a logged-in zsxq account; cookies wiped by browser profile reset; zsxq rotating session tokens server-side.

Related errors

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