What causes "cursor must be a non-negative integer string" in jackwener/OpenCLI?

Pass a plain digit string, e.g. --cursor 0 to start from the beginning.

jackwener/OpenCLI · error · ArgumentError

cursor must be a non-negative integer string

Error message

cursor must be a non-negative integer string

What it means

requireCursor validates the pagination cursor for creator-videos. A cursor must be a string of digits (non-negative integer); anything else — negative numbers, letters, empty-after-trim strings — throws this ArgumentError. TikTok Studio item_list uses a numeric offset cursor, so the library rejects malformed values before hitting the network.

Source

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

const SERVER_PAGE_MAX = 50;

function requirePositiveInt(value, label, defaultValue, maxValue) {
    const raw = value ?? defaultValue;
    const parsed = Number(raw);
    if (!Number.isInteger(parsed) || parsed <= 0) {
        throw new ArgumentError(`${label} must be a positive integer`, `Example: opencli tiktok creator-videos --${label} ${defaultValue}`);
    }
    if (parsed > maxValue) {
        throw new ArgumentError(`${label} must be <= ${maxValue}`, `Example: opencli tiktok creator-videos --${label} ${maxValue}`);
    }
    return parsed;
}

function requireCursor(value) {
    const raw = value ?? '0';
    const text = String(raw).trim();
    if (!/^\d+$/.test(text)) {
        throw new ArgumentError('cursor must be a non-negative integer string', 'Example: opencli tiktok creator-videos --cursor 0');
    }
    const cursor = Number(text);
    if (!Number.isSafeInteger(cursor)) {
        throw new ArgumentError('cursor must be a safe integer', 'Example: opencli tiktok creator-videos --cursor 0');
    }
    return cursor;
}

function buildItemListRequest(cursor, size) {
    return {
        cursor,
        size,
        query: {
            conditions: [],
            sort_orders: [{ field_name: 'create_time', order: 2 }],
        },
    };
}

View on GitHub (pinned to 49907e53dc)

Solutions

Pass a plain digit string, e.g. --cursor 0 to start from the beginning.
Use the exact nextCursor value returned verbatim by the previous call.
If a saved cursor looks corrupted, discard it and restart pagination from cursor 0.

Example fix

// before
opencli tiktok creator-videos --cursor page-3
// after
opencli tiktok creator-videos --cursor 150

Defensive patterns

Strategy: validation

Validate before calling

const cursor = (process.env.TT_CURSOR ?? '0').trim();
if (!/^\d+$/.test(cursor)) {
  throw new Error(`cursor must be a non-negative integer string, got: '${cursor}'`);
}

Type guard

const isValidCursor = (v) => typeof v === 'string' || typeof v === 'number';
const usableCursor = (v) => /^\d+$/.test(String(v ?? '0').trim());

Try / catch

try {
  await run(['tiktok', 'creator-videos', '--cursor', rawCursor]);
} catch (e) {
  if (String(e.message).includes('cursor must be a non-negative integer')) {
    console.error(`Invalid cursor '${rawCursor}', restarting from 0`);
    await run(['tiktok', 'creator-videos', '--cursor', '0']);
  } else throw e;
}

Prevention

Persist and reuse nextCursor values verbatim, never edit them by hand.
Default to --cursor 0 when starting a fresh pagination.
Sanitize cursors loaded from state files with a /^\d+$/ check.

When it happens

Trigger: Running `opencli tiktok creator-videos --cursor -1`, `--cursor abc`, `--cursor ''`, or piping a non-numeric nextCursor value from a corrupted state file.

Common situations: Hand-editing or truncating a cursor saved from a previous run; mixing cursors between different commands; copying a cursor that includes surrounding text.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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