jackwener/OpenCLI · error · CommandExecutionError

semanticscholar ${label} row is missing paperId

Error message

semanticscholar ${label} row is missing paperId

What it means

normalizePaperRow requires every paper row to carry a non-empty string paperId, the canonical Semantic Scholar identifier. A row that is an object but lacks paperId (empty, missing, or non-string) triggers this error. paperId is required because the adapter derives the paper URL from it.

Source

Thrown at clis/semanticscholar/utils.js:167

        return first.name.trim();
    }
    return '';
}

export function optionalNumber(value, label) {
    if (value == null) return null;
    if (typeof value !== 'number' || !Number.isFinite(value)) {
        throw new CommandExecutionError(`semanticscholar ${label} must be a number when present`);
    }
    return value;
}

export function normalizePaperRow(paper, label, { rank } = {}) {
    if (!paper || typeof paper !== 'object') {
        throw new CommandExecutionError(`semanticscholar ${label} row is not an object`);
    }
    if (typeof paper.paperId !== 'string' || !paper.paperId.trim()) {
        throw new CommandExecutionError(`semanticscholar ${label} row is missing paperId`);
    }
    if (typeof paper.title !== 'string' || !paper.title.trim()) {
        throw new CommandExecutionError(`semanticscholar ${label} row is missing title`);
    }
    if (paper.authors != null && !Array.isArray(paper.authors)) {
        throw new CommandExecutionError(`semanticscholar ${label} row has malformed authors`);
    }
    const row = {
        paperId: paper.paperId.trim(),
        doi: pickDoi(paper.externalIds),
        title: paper.title.trim(),
        year: optionalNumber(paper.year, `${label} year`),
        firstAuthor: firstAuthorName(paper.authors),
        citationCount: optionalNumber(paper.citationCount, `${label} citationCount`),
        url: typeof paper.url === 'string' && paper.url.trim()
            ? paper.url.trim()
            : `https://www.semanticscholar.org/paper/${paper.paperId.trim()}`,
    };

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Ensure the request's `fields` query parameter includes `paperId` (and `title`).
  2. Filter out rows without paperId before normalizing.
  3. Retry with a canonical ref (DOI or arXiv id) if a specific record is incomplete.
  4. Check whether the API version changed row shape and update the adapter.

Example fix

// before
fetch(`${S2_GRAPH_BASE}/paper/${ref}/citations?fields=title`)
// after
fetch(`${S2_GRAPH_BASE}/paper/${ref}/citations?fields=paperId,title,year,authors,citationCount`)
Defensive patterns

Strategy: validation

Validate before calling

// Request paperId explicitly and pre-filter rows
const url = `${S2_GRAPH_BASE}/paper/${ref}/citations?fields=paperId,title,year,authors,citationCount`;
const usable = (data.data ?? []).filter(r => typeof r?.paperId === 'string' && r.paperId.trim());

Type guard

function hasPaperId(v) {
  return v !== null && typeof v === 'object' && typeof v.paperId === 'string' && v.paperId.trim().length > 0;
}

Try / catch

try {
  return normalizePaperRow(paper, 'citation');
} catch (err) {
  if (/missing paperId/.test(err.message)) return null; // skip incomplete record
  throw err;
}

Prevention

When it happens

Trigger: A citation/reference/recommendations row is an object but its paperId field is missing, empty string, or whitespace-only — often for records where S2 hasn't ingested full metadata.

Common situations: Newly indexed or partially ingested papers lacking ids; API field selection omitting paperId from the `fields` query param so the response never includes it.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

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