What causes "TikTok Studio item_list requires login: ${statusMsg}" in jackwener/OpenCLI?

Re-authenticate with the CLI's TikTok login flow and retry.

jackwener/OpenCLI · error · AuthRequiredError

TikTok Studio item_list requires login: ${statusMsg}

Error message

TikTok Studio item_list requires login: ${statusMsg}

What it means

A second auth check in assertApiSuccess: even when status_code is 0 or absent, if a non-success status_msg matches the auth-failure regex, the library raises AuthRequiredError for www.tiktok.com. This catches TikTok responses that signal login problems via the message text alone.

Source

Thrown at clis/tiktok/creator-videos.js:126

function unwrapPayload(data) {
    if (!data || typeof data !== 'object') {
        throw new CommandExecutionError('TikTok Studio item_list returned an empty response');
    }
    return data.data && typeof data.data === 'object' ? data.data : data;
}

function assertApiSuccess(data) {
    const statusCode = data.status_code ?? data.statusCode;
    const statusMsg = String(data.status_msg ?? data.statusMsg ?? '').trim();
    if (statusCode !== undefined && Number(statusCode) !== 0) {
        if (looksAuthFailure(statusMsg)) {
            throw new AuthRequiredError('www.tiktok.com', `TikTok Studio item_list requires login: ${statusMsg || statusCode}`);
        }
        throw new CommandExecutionError(`TikTok Studio item_list failed: ${statusMsg || statusCode}`);
    }
    if (statusMsg && !/^(success|ok)$/i.test(statusMsg)) {
        if (looksAuthFailure(statusMsg)) {
            throw new AuthRequiredError('www.tiktok.com', `TikTok Studio item_list requires login: ${statusMsg}`);
        }
        throw new CommandExecutionError(`TikTok Studio item_list failed: ${statusMsg}`);
    }
}

function normalizeNumber(value) {
    const n = Number(value);
    return Number.isFinite(n) ? n : 0;
}

function formatDate(value) {
    const seconds = Number(value);
    if (!Number.isFinite(seconds) || seconds <= 0) return '';
    return new Date(seconds * 1000).toLocaleString('zh-CN', {
        timeZone: 'Asia/Shanghai',
        hour12: false,
    });
}

View on GitHub (pinned to 49907e53dc)

Solutions

Re-authenticate with the CLI's TikTok login flow and retry.
Re-export fresh cookies from a logged-in browser session.
Confirm no other device/process is invalidating the session concurrently.

Example fix

// before
const page = await fetchCreatorVideosPage(...); // AuthRequiredError
// after
if (!(await tiktokSessionValid())) {
  await tiktokLogin();
}
const page = await fetchCreatorVideosPage(...);

Defensive patterns

Strategy: try-catch

Validate before calling

const cookies = await loadCookies('www.tiktok.com');
if (!cookies || cookies.length === 0) {
  throw new Error('No TikTok cookies found; run login first');
}

Try / catch

try {
  const videos = await listCreatorVideos(opts);
} catch (e) {
  if (String(e.message).includes('requires login')) {
    await tiktokLogin('www.tiktok.com');
    return listCreatorVideos(opts);
  }
  throw e;
}

Prevention

Re-export cookies from a freshly logged-in browser for CI runs.
Detect session staleness with a cheap authenticated endpoint before batch jobs.
Handle AuthRequiredError with an automatic re-login path.
Keep one canonical login session to avoid concurrent logouts.

When it happens

Trigger: item_list returns success-ish statusCode but status_msg like 'not logged in' or 'unauthorized user' — e.g. stale session cookies accepted at transport level but rejected logically.

Common situations: Half-expired sessions; cookies for the wrong domain; account logged out elsewhere mid-run; running the CLI in CI where cookies were exported from a machine that has since logged out.

Related errors

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