jackwener/OpenCLI · error · AuthRequiredError

Suno session check failed (${detail}). Open https://suno.com

Error message

Suno session check failed (${detail}). Open https://suno.com in Chrome and sign in, then retry.

What it means

ensureSunoSession runs an in-browser check of your suno.com Clerk session before API calls. When the check fails with an auth signal (result.auth true, or HTTP 401/403), it throws AuthRequiredError telling you to open suno.com in Chrome and sign in, since the CLI reuses your browser's JWT.

Source

Thrown at clis/suno/utils.js:207

            const res = await fetch('${STUDIO_API}/api/billing/info/', { headers: ${sunoHeadersJs(deviceId)} });
            if (!res.ok) return { ok: false, status: res.status, body: (await res.text()).slice(0, 300) };
            let data = null;
            try {
                data = await res.json();
            } catch (e) {
                return { ok: false, error: 'Malformed billing/info JSON: ' + String(e).slice(0, 200) };
            }
            const parse = ${parseSunoBillingInfo.toString()};
            return { ok: true, ...parse(data) };
        } catch (e) {
            return { ok: false, error: String(e).slice(0, 200) };
        }
    })()`));

    if (!result || !result.ok) {
        const detail = result?.status || result?.error || 'unknown';
        if (result?.auth || result?.status === 401 || result?.status === 403) {
            throw new AuthRequiredError(SUNO_DOMAIN, `Suno session check failed (${detail}). Open https://suno.com in Chrome and sign in, then retry.`);
        }
        throw new CommandExecutionError(`Suno session check failed (${detail}).`);
    }
    return { ...result, deviceId };
}

/**
 * Verify the captcha pre-flight. If `required:true`, the simple flow won't
 * work without solving a CAPTCHA (out of scope for the headless adapter).
 */
export async function checkSunoCaptcha(page, deviceId) {
    const result = unwrapEvaluateResult(await page.evaluate(`(async () => {
        const res = await fetch('${STUDIO_API}/api/c/check', {
            method: 'POST',
            headers: ${sunoHeadersJs(deviceId, { 'Content-Type': 'application/json' })},
            body: JSON.stringify({ ctype: 'generation' }),
        });
        if (!res.ok) return { ok: false, status: res.status };

View on GitHub (pinned to 49907e53dc)

Solutions

Open https://suno.com in the Chrome instance the CLI controls and sign in, then retry the command.
Clear suno.com cookies for that profile and log in again to remove stale/invalid session state.
Verify you are not in an incognito/isolated profile where the Clerk cookie is dropped.
If the status is 403 persistently, check for a captcha/Cloudflare challenge on suno.com and complete it in the browser first.
Update the CLI in case Suno changed its auth endpoints and a newer version handles the new flow.

Example fix

// before (headless invocation with no signed-in profile)
opencli suno list   // -> AuthRequiredError
// after (ensure sign-in first, then run)
// 1. open https://suno.com in Chrome and log in
opencli suno list

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: verify sign-in state before running commands
const ok = await ensureSunoSession(page, deviceId).then(() => true).catch(() => false);
if (!ok) console.error('Sign in at https://suno.com in the automated Chrome first.');

Type guard

function isAuthRequiredError(err) {
  return err && (err.name === 'AuthRequiredError' || /session check failed.*sign in/i.test(err.message || ''));
}

Try / catch

try {
  await ensureSunoSession(page, deviceId);
  await runCommand();
} catch (err) {
  if (isAuthRequiredError(err)) {
    console.error('Open https://suno.com in Chrome, sign in, then retry.');
    process.exitCode = 2; // distinct auth exit code
  } else throw err;
}

Prevention

Sign in to suno.com in the exact Chrome profile the CLI drives before long sessions.
Re-login after password changes or known session invalidations.
Run `suno status` as a cheap pre-flight before expensive operations.
Avoid incognito/isolated profiles that drop the Clerk session cookie.

When it happens

Trigger: Running any suno command when you are logged out of suno.com in the automated Chrome profile, your Clerk JWT expired, or the session endpoint returns 401/403 (e.g. stale cookies after a password change or Cloudflare challenge).

Common situations: Chrome profile signed out after cookie eviction or incognito use; expired Clerk session after long idle; logging in on a different browser than the one the CLI drives; suno.com invalidated all sessions (password change, security event).

Related errors

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