jackwener/OpenCLI · info · EmptyResultError
pubmed related
Error message
pubmed related
What it means
This EmptyResultError ('pubmed related') is thrown when the ELink neighbor_score call returns no usable link list for the given PMID. Either the response lacks `linksets[0].linksetdbs[0].links` (not an array) or the links array is empty, meaning PubMed has no scored related articles for that record.
Source
Thrown at clis/pubmed/related.js:30
browser: false,
args: [
{ name: 'pmid', positional: true, required: true, help: 'PubMed ID, e.g. 37780221' },
{ name: 'limit', type: 'int', default: 20, help: 'Max results (1-100)' },
{ name: 'score', type: 'boolean', default: false, help: 'Show similarity scores when available' },
],
columns: RELATED_COLUMNS,
func: async (args) => {
const pmid = requirePmid(args.pmid);
const limit = requireBoundedInt(args.limit, 20, 100);
const result = await eutilsFetch('elink', {
id: pmid,
dbfrom: 'pubmed',
cmd: 'neighbor_score',
linkname: 'pubmed_pubmed',
}, { label: 'pubmed related' });
const rawLinks = result?.linksets?.[0]?.linksetdbs?.[0]?.links;
if (!Array.isArray(rawLinks) || rawLinks.length === 0) {
throw new EmptyResultError('pubmed related', `No related articles found for PMID ${pmid}.`);
}
const links = rawLinks
.map(link => typeof link === 'string' ? { id: link, score: null } : { id: String(link?.id ?? ''), score: Number.isFinite(Number(link?.score)) ? Number(link.score) : null })
.filter(link => link.id && link.id !== pmid)
.slice(0, limit);
if (links.length === 0) {
throw new EmptyResultError('pubmed related', `No related articles found for PMID ${pmid}.`);
}
const rows = await fetchSummaryRows(links.map(link => link.id), 'pubmed related summary');
return rows.map((row, index) => ({
...row,
score: args.score ? links[index].score : null,
}));
},
});
View on GitHub (pinned to 49907e53dc)
Solutions
- Verify the PMID exists via esummary or a direct PubMed lookup
- Retry later — related-article scores are computed periodically and may be absent for brand-new records
- Check for rate limiting / add an api_key if the response body is malformed rather than empty
- Use a different seed PMID (e.g. the corrected/newer version of a merged record)
Defensive patterns
Strategy: try-catch
Validate before calling
// Verify the PMID exists and is a PubMed article before asking for related items
const sum = await eutilsFetch('esummary', { db: 'pubmed', id: pmid }, { label: 'probe' });
if (!sum?.result?.[String(pmid)]) console.warn(`PMID ${pmid} not found — related lookup will likely be empty`); Type guard
function hasRawLinks(res) {
const links = res?.linksets?.[0]?.linksetdbs?.[0]?.links;
return Array.isArray(links) && links.length > 0;
} Try / catch
try {
return await clis.pubmedRelated({ pmid, limit });
} catch (e) {
if (e.name === 'EmptyResultError' && e.scope === 'pubmed related') {
return []; // no neighbors yet — render empty state
}
throw e;
} Prevention
- Validate PMIDs (8-digit numeric strings) before calling
- Handle brand-new PMIDs having no related-score data yet
- Add an api_key to avoid malformed error bodies that also surface as empty linksets
- Cache negative results briefly to avoid hammering ELink for known-empty PMIDs
When it happens
Trigger: Passing a PMID that does not exist or was withdrawn (ELink returns an empty/error linkset); a very recent article with no computed neighbors yet; the ELink API returning an error body so `rawLinks` is undefined.
Common situations: Typo in the PMID; querying a preprint- or book-record PMID that has no pubmed_pubmed links; NCBI rate limiting causing malformed ELink responses; old PMIDs merged into other records.
Related errors
AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29).
Data as JSON: /api/errors/d0644fb969a391f0.
Report an issue: GitHub.