jackwener/OpenCLI · error · ArgumentError

semanticscholar citations offset must be a non-negative inte

Error message

semanticscholar citations offset must be a non-negative integer

What it means

The semanticscholar citations command (clis/semanticscholar/citations.js:38) validates the pagination offset client-side before building the API URL. An ArgumentError is thrown when the offset is missing-integer or negative — i.e. not a whole number >= 0. This is input validation, not a network issue.

Source

Thrown at clis/semanticscholar/citations.js:38

    name: 'citations',
    access: 'read',
    description: 'List papers that cite a Semantic Scholar paper (paginated)',
    domain: 'api.semanticscholar.org',
    strategy: Strategy.PUBLIC,
    browser: false,
    args: [
        { name: 'id', positional: true, required: true, help: 'paperId (40-char hex), DOI, arXiv id, or prefixed id' },
        { name: 'limit', type: 'int', default: 20, help: 'Max citing papers (1-1000, single Semantic Scholar page)' },
        { name: 'offset', type: 'int', default: 0, help: 'Page offset (0-based)' },
    ],
    columns: ['rank', 'paperId', 'doi', 'title', 'year', 'firstAuthor', 'citationCount', 'url'],
    func: async (args) => {
        const ref = requirePaperRef(args.id);
        const limit = requireBoundedInt(args.limit, 20, 1000);
        const offsetRaw = args.offset ?? 0;
        const offset = typeof offsetRaw === 'number' ? offsetRaw : Number(offsetRaw);
        if (!Number.isInteger(offset) || offset < 0) {
            throw new ArgumentError('semanticscholar citations offset must be a non-negative integer');
        }
        if (offset > 9999) {
            throw new ArgumentError('semanticscholar citations offset must be <= 9999');
        }
        const url = `${S2_GRAPH_BASE}/paper/${encodeURIComponent(ref)}/citations?fields=${FIELDS}&limit=${limit}&offset=${offset}`;
        const body = await s2Fetch(url, 'semanticscholar citations');

        const data = Array.isArray(body?.data) ? body.data : null;
        if (data === null) {
            throw new CommandExecutionError('semanticscholar citations returned an unexpected payload shape');
        }
        if (!data.length) {
            throw new EmptyResultError('semanticscholar citations', `No Semantic Scholar citations for "${args.id}" at offset ${offset}.`);
        }

        return data.slice(0, limit).map((entry, i) => {
            if (!entry || typeof entry !== 'object' || !('citingPaper' in entry)) {
                throw new CommandExecutionError('semanticscholar citations row is missing citingPaper');

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a non-negative integer offset (0-based), e.g. --offset 0, 20, 40.
2. Fix the pagination loop so page N uses offset = N * limit with N >= 0.
3. Ensure the variable being interpolated is set and numeric before invoking the command.
4. Use the default (omit --offset) to start from the first page.

Example fix

// before
const offset = Number(process.env.PAGE) - 2; // can go negative
await cli('semanticscholar citations', id, { offset });
// after
const offset = Math.max(0, (Number(process.env.PAGE) - 1) * limit);
await cli('semanticscholar citations', id, { offset: Number.isInteger(offset) ? offset : 0 });

function safeOffset(raw) {
  const n = typeof raw === 'number' ? raw : Number(raw);
  if (!Number.isInteger(n) || n < 0) throw new TypeError(`offset must be a non-negative integer, got ${JSON.stringify(raw)}`);
  return n;
}
// call before invoking:
safeOffset(args.offset ?? 0);

function isValidOffset(v) {
  const n = typeof v === 'number' ? v : Number(v);
  return Number.isInteger(n) && n >= 0;
}

try {
  await cli('semanticscholar citations', id, { offset });
} catch (err) {
  if (/offset must be a non-negative integer/.test(err.message)) {
    console.error(`Bad --offset value: ${JSON.stringify(offset)}; using 0`);
    return cli('semanticscholar citations', id, { offset: 0 });
  }
  throw err;
}

When it happens

Trigger: Calling `semanticscholar citations <id> --offset -5`, passing a non-numeric string like "abc" or "1.5", or a float/negative value via a script that forwards raw user input into args.offset.

Common situations: Pagination loops that decrement below zero; shell scripts interpolating unset variables (empty/negative values); confusing 0-based vs 1-based paging and passing offset=-1; passing strings like "page3" instead of integers.

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

• ${label} must be a positive integer
• ${label} must be <= ${maxValue}
• semanticscholar citations offset must be <= 9999
• --max-pages must be an integer between 1 and ${HARD_MAX_PAGI
• zhihu collection --${name} must be a non-negative integer

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