jackwener/OpenCLI · info · EmptyResultError

No Semantic Scholar citations for "${args.id}" at offset ${o

Error message

No Semantic Scholar citations for "${args.id}" at offset ${offset}.

What it means

This EmptyResultError (clis/semanticscholar/citations.js:51) is thrown when the citations endpoint responded correctly but the `data` array was empty at the requested offset. The library treats an empty page as a distinct, expected outcome rather than a failure of the request itself.

Source

Thrown at clis/semanticscholar/citations.js:51

        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');
            }
            return normalizePaperRow(entry.citingPaper, 'citations', { rank: offset + i + 1 });
        });
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

Retry with --offset 0 to confirm the paper has any citations at all.
In pagination loops, catch EmptyResultError and treat it as the normal end-of-results signal.
Check the paper's citationCount (via `semanticscholar paper <id>`) and stop paging at or before it.
Verify the paper id resolves to the intended paper.

Example fix

// before
let offset = 0;
while (true) { rows = await citations(id, offset); offset += limit; }
// after
let offset = 0;
try {
  while (true) { rows = await citations(id, offset); offset += limit; }
} catch (err) {
  if (!isEmptyResult(err)) throw err; // end of pagination, not a failure
}

Defensive patterns

Strategy: fallback

Validate before calling

// Check citationCount before deep paging:
const paper = await cli('semanticscholar paper', id, { json: true });
if (offset >= paper.citationCount) return []; // would be empty — skip the call

Type guard

function isEmptyResultError(err) {
  return err instanceof Error && err.name === 'EmptyResultError';
}

Try / catch

try {
  rows = await citations(id, offset);
} catch (err) {
  if (isEmptyResultError(err)) {
    return { rows: [], done: true }; // normal end of pagination
  }
  throw err;
}

Prevention

Treat EmptyResultError as end-of-results in pagination loops, not as failure.
Use the paper's citationCount to bound offset before paging.
Retry with offset 0 first to distinguish 'no citations at all' from 'bad offset'.
Never loop unconditionally without an empty-page termination condition.

When it happens

Trigger: Requesting an offset past the last citation (e.g. offset 500 for a paper with 320 citations); citing a paper that genuinely has zero citations; passing an offset > 0 with a limit that skips past all results.

Common situations: Auto-pagination loops that page one past the end; querying very new or obscure papers with no citing papers yet; computing offset from stale counts after citations changed; users assuming a paper has citations it does not have.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

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