{"record":{"id":"57434fe223a4fec3","repo":"jackwener/OpenCLI","slug":"cursor-must-be-a-non-negative-integer-string","errorCode":null,"errorMessage":"cursor must be a non-negative integer string","messagePattern":"cursor must be a non-negative integer string","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/tiktok/creator-videos.js","lineNumber":32,"sourceCode":"const SERVER_PAGE_MAX = 50;\n\nfunction requirePositiveInt(value, label, defaultValue, maxValue) {\n    const raw = value ?? defaultValue;\n    const parsed = Number(raw);\n    if (!Number.isInteger(parsed) || parsed <= 0) {\n        throw new ArgumentError(`${label} must be a positive integer`, `Example: opencli tiktok creator-videos --${label} ${defaultValue}`);\n    }\n    if (parsed > maxValue) {\n        throw new ArgumentError(`${label} must be <= ${maxValue}`, `Example: opencli tiktok creator-videos --${label} ${maxValue}`);\n    }\n    return parsed;\n}\n\nfunction requireCursor(value) {\n    const raw = value ?? '0';\n    const text = String(raw).trim();\n    if (!/^\\d+$/.test(text)) {\n        throw new ArgumentError('cursor must be a non-negative integer string', 'Example: opencli tiktok creator-videos --cursor 0');\n    }\n    const cursor = Number(text);\n    if (!Number.isSafeInteger(cursor)) {\n        throw new ArgumentError('cursor must be a safe integer', 'Example: opencli tiktok creator-videos --cursor 0');\n    }\n    return cursor;\n}\n\nfunction buildItemListRequest(cursor, size) {\n    return {\n        cursor,\n        size,\n        query: {\n            conditions: [],\n            sort_orders: [{ field_name: 'create_time', order: 2 }],\n        },\n    };\n}","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/tiktok/creator-videos.js#L14-L50","documentation":"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.","triggerScenarios":"Running `opencli tiktok creator-videos --cursor -1`, `--cursor abc`, `--cursor ''`, or piping a non-numeric nextCursor value from a corrupted state file.","commonSituations":"Hand-editing or truncating a cursor saved from a previous run; mixing cursors between different commands; copying a cursor that includes surrounding text.","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."],"exampleFix":"// before\nopencli tiktok creator-videos --cursor page-3\n// after\nopencli tiktok creator-videos --cursor 150","handlingStrategy":"validation","validationCode":"const cursor = (process.env.TT_CURSOR ?? '0').trim();\nif (!/^\\d+$/.test(cursor)) {\n  throw new Error(`cursor must be a non-negative integer string, got: '${cursor}'`);\n}","typeGuard":"const isValidCursor = (v) => typeof v === 'string' || typeof v === 'number';\nconst usableCursor = (v) => /^\\d+$/.test(String(v ?? '0').trim());","tryCatchPattern":"try {\n  await run(['tiktok', 'creator-videos', '--cursor', rawCursor]);\n} catch (e) {\n  if (String(e.message).includes('cursor must be a non-negative integer')) {\n    console.error(`Invalid cursor '${rawCursor}', restarting from 0`);\n    await run(['tiktok', 'creator-videos', '--cursor', '0']);\n  } else throw e;\n}","preventionTips":["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."],"tags":["argument-validation","pagination","cli","tiktok"],"backgroundTag":"invalid-argument-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}