jackwener/OpenCLI · error · AuthRequiredError

Auth refresh quickCheck failed for ${cmd.site}

Error message

Auth refresh quickCheck failed for ${cmd.site}

What it means

The auth refresh command re-validates a site's login state by navigating to the refresh URL and running quickCheck. If the quick check does not conclusively report logged-in, it throws AuthRequiredError, meaning the stored session/profile for that site cannot be refreshed and the user must re-authenticate interactively.

Source

Thrown at src/commands/auth.ts:229

    error: code ? `${code}: ${message}` : message,
  };
}

function refreshCommand(cmd: CliCommand, timeoutSeconds: number): BrowserCliCommand | null {
  if (cmd.browser !== true) return null;
  let refreshFunc = cmd.authStatus?.refresh;
  if (typeof refreshFunc !== 'function') {
    const quickCheck = cmd.authStatus?.quickCheck;
    if (typeof quickCheck !== 'function' || !cmd.domain) return null;
    const refreshUrl = cmd.domain.startsWith('http://') || cmd.domain.startsWith('https://')
      ? cmd.domain
      : `https://${cmd.domain}`;
    refreshFunc = async (page, kwargs, debug) => {
      await page.goto(refreshUrl);
      await page.wait(1);
      const loggedIn = normalizeQuickResult(await quickCheck(page, kwargs, debug));
      if (loggedIn !== true) {
        throw new AuthRequiredError(cmd.domain ?? cmd.site, `Auth refresh quickCheck failed for ${cmd.site}`);
      }
      return { status: 'touched' };
    };
  }
  return withTimeoutArg({
    ...cmd,
    func: refreshFunc,
    navigateBefore: false,
    siteSession: 'persistent',
    defaultWindowMode: 'background',
  }, timeoutSeconds) as BrowserCliCommand;
}

function normalizeRefreshStatus(result: unknown): 'refreshed' | 'touched' {
  if (result && typeof result === 'object' && !Array.isArray(result)) {
    const row = result as Record<string, unknown>;
    if (row.status === 'refreshed' || row.refreshed === true) return 'refreshed';
  }

View on GitHub (pinned to 49907e53dc)

Solutions

1. Re-authenticate interactively for that site (opencli auth login / whoami flow) to refresh stored credentials.
2. Verify the --domain/--site points at the environment the profile is actually logged into.
3. Check the target site is reachable and not redirecting to an SSO/login wall; retry after network issues.
4. Delete the stale profile for the site and log in again from scratch.

Example fix

// before
opencli auth refresh --site acme
// AuthRequiredError: Auth refresh quickCheck failed for acme
// after
opencli auth login --site acme   # re-establish session
opencli auth refresh --site acme

const status = await opencli.authWhoami({ sites: [site] });
if (status !== 'logged-in') {
  console.warn(`Session for ${site} is '${status}'; run auth login before refresh.`);
}

function isRefreshable(status: string): boolean {
  return status === 'logged-in';
}

try {
  await opencli.authRefresh({ site });
} catch (e) {
  if (e.name === 'AuthRequiredError') {
    console.error(`Session for ${site} expired; re-run: opencli auth login --site ${site}`);
  } else throw e;
}

When it happens

Trigger: Running `opencli auth refresh --site <site>` when the stored cookies/session for that site have expired or been invalidated; the site redirects to a login page during quickCheck; the domain override points at an environment where the profile is not logged in.

Common situations: Long-lived CI machines whose saved auth profiles expired; site-side session revocation (password change, SSO policy); refreshing against a wrong --domain (e.g. staging) that the profile isn't logged into.

Related errors

• 请先在共享 Chrome 完成 1688 登录/验证，再重试（${action}）
• Bilibili ${label} API requires login or permission: ${messag
• bilibili.com
• ${probe.detail}
• result.detail (auth required from Claude probe)

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