jackwener/OpenCLI · error · AuthRequiredError

auth

Error message

auth

What it means

`verifyHfIdentity` in `clis/hf/auth.js` injects a whoami probe into a logged-in browser page on huggingface.co. When the probe reports `kind === 'auth'`, the user is not authenticated with Hugging Face, so the library throws `AuthRequiredError('huggingface.co', detail)`. It exists to fail fast with an actionable 'log in first' message instead of failing later on authenticated API calls.

Source

Thrown at clis/hf/auth.js:23

// documented /api/whoami-v2 endpoint (401 when anonymous) via a no-nav probe.
const WHOAMI_PROBE = `(async () => {
  try {
    const r = await fetch('/api/whoami-v2', { credentials: 'include', headers: { Accept: 'application/json' } });
    if (r.status === 401 || r.status === 403) return { kind: 'auth', detail: 'HF /api/whoami-v2 HTTP ' + r.status };
    if (!r.ok) return { kind: 'http', httpStatus: r.status };
    const d = await r.json();
    if (!d || !d.name || d.type === undefined) return { kind: 'auth', detail: 'HF /api/whoami-v2 has no name — anonymous' };
    return { ok: true, username: String(d.name), fullname: String(d.fullname || ''), type: String(d.type || '') };
  } catch (e) {
    return { kind: 'exception', detail: String(e && e.message || e) };
  }
})()`;

async function verifyHfIdentity(page) {
  await page.goto('https://huggingface.co/');
  await page.wait(1);
  const probe = await page.evaluate(WHOAMI_PROBE);
  if (probe?.kind === 'auth') throw new AuthRequiredError('huggingface.co', probe.detail);
  if (probe?.kind === 'http') throw new CommandExecutionError(`HTTP ${probe.httpStatus} from HF /api/whoami-v2`);
  if (probe?.kind === 'exception') throw new CommandExecutionError(`HF whoami failed: ${probe.detail}`);
  if (!probe?.ok) throw new CommandExecutionError(`Unexpected HF probe: ${JSON.stringify(probe)}`);
  return { username: probe.username, fullname: probe.fullname, type: probe.type };
}

registerSiteAuthCommands({
  site: 'hf',
  domain: 'huggingface.co',
  loginUrl: 'https://huggingface.co/login',
  columns: ['username', 'fullname', 'type'],
  verify: verifyHfIdentity,
  poll: async (page) => {
    const probe = await page.evaluate(WHOAMI_PROBE);
    if (!probe?.ok) throw new AuthRequiredError('huggingface.co', 'Waiting for Hugging Face login');
    return { username: probe.username, fullname: probe.fullname, type: probe.type };
  },
});

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Open https://huggingface.co/ in the browser the CLI drives and log in (create an account if needed)
  2. Re-run the hf command after confirming you see your avatar/username on the homepage
  3. If sessions keep dropping, check that cookies for huggingface.co are not being blocked/cleared by browser settings or extensions

Example fix

// before (not logged in) -> AuthRequiredError
const me = await verifyHfIdentity(page);
// after: log in at https://huggingface.co/login in the controlled browser first,
// then re-run
const me = await verifyHfIdentity(page);
Defensive patterns

Strategy: try-catch

Validate before calling

// Check login state before running auth-dependent hf commands
const res = await fetch('https://huggingface.co/api/whoami-v2', {
  headers: { Authorization: `Bearer ${process.env.HF_TOKEN}` },
});
if (!res.ok) {
  throw new Error('Not authenticated with Hugging Face — log in at https://huggingface.co/login');
}

Type guard

function isAuthedWhoami(probe) {
  return probe != null && probe.ok === true && typeof probe.username === 'string';
}

Try / catch

try {
  const me = await verifyHfIdentity(page);
} catch (e) {
  if (e.name === 'AuthRequiredError') {
    console.error('Log in to huggingface.co in the controlled browser, then retry.');
    await page.goto('https://huggingface.co/login');
  } else throw e;
}

Prevention

When it happens

Trigger: Running an `hf` command that needs identity verification while the browser session has no valid Hugging Face login (no session cookie, or expired session); being logged out or using a fresh/incognito browser profile; HF clearing or invalidating the session token server-side.

Common situations: CI or fresh containers where the browser profile was never logged in; session expiry after weeks of inactivity; logging out of huggingface.co manually between runs; cookie jars wiped by browser updates or privacy cleaners.

Related errors

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