jackwener/OpenCLI · info · EmptyResultError

pubmed citations

Error message

pubmed citations

What it means

EmptyResultError('pubmed citations') thrown at clis/pubmed/citations.js:32 when the ELink 'neighbor' response has no links: result.linksets[0].linksetdbs[0].links is not an array or is empty for the requested direction (cited-by or references) of the given PMID. The CLI treats this as 'no links found', a normal outcome for new or unlinked articles, not an API error.

Source

Thrown at clis/pubmed/citations.js:32

        { name: 'pmid', positional: true, required: true, help: 'PubMed ID, e.g. 37780221' },
        { name: 'direction', default: 'citedby', choices: ['citedby', 'references'], help: 'citedby or references' },
        { name: 'limit', type: 'int', default: 20, help: 'Max results (1-100)' },
    ],
    columns: LINK_COLUMNS,
    func: async (args) => {
        const pmid = requirePmid(args.pmid);
        const direction = requireChoice(args.direction, ['citedby', 'references'], 'direction', 'citedby');
        const limit = requireBoundedInt(args.limit, 20, 100);
        const linkname = direction === 'citedby' ? 'pubmed_pubmed_citedin' : 'pubmed_pubmed_refs';
        const result = await eutilsFetch('elink', {
            id: pmid,
            dbfrom: 'pubmed',
            cmd: 'neighbor',
            linkname,
        }, { label: 'pubmed citations' });
        const links = result?.linksets?.[0]?.linksetdbs?.[0]?.links;
        if (!Array.isArray(links) || links.length === 0) {
            throw new EmptyResultError('pubmed citations', `No ${direction} links found for PMID ${pmid}.`);
        }
        return fetchSummaryRows(links.slice(0, limit).map(String), 'pubmed citations summary');
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Verify the PMID exists and check its citation count on the PubMed website before scripting
2. For recent papers, wait — cited-by indexing lags publication by weeks/months
3. Try the opposite direction (references vs cited-by) to see if the record has any links
4. If you have a DOI, confirm the PMID mapping first (esearch) so you aren't querying a dead id
5. Treat this as an expected empty state in your tooling rather than retrying aggressively

Example fix

// before
const links = result?.linksets?.[0]?.linksetdbs?.[0]?.links;
if (!Array.isArray(links) || links.length === 0) {
    throw new EmptyResultError('pubmed citations', `No ${direction} links found for PMID ${pmid}.`);
}
// after
const links = result?.linksets?.[0]?.linksetdbs?.[0]?.links ?? [];
if (links.length === 0) {
    console.warn(`No ${direction} links for PMID ${pmid}; the article may be too new or unlinked.`);
    return [];
}

// resolve the PMID and its existence first via esearch
const hit = await runCli('pubmed esearch', { term: `${pmid}[uid]` });
if (!hit || hit.length === 0) throw new Error(`PMID ${pmid} not found in PubMed`);

try {
  const cites = await runCli('pubmed citations', { pmid, direction });
} catch (e) {
  if (e instanceof EmptyResultError || /No .* links found/.test(e.message)) {
    console.warn(`PMID ${pmid} has no ${direction} links yet — returning empty set.`);
    return [];
  }
  throw e;
}

When it happens

Trigger: (a) the PMID has no citing articles yet (direction=cited-by on a very recent paper), (b) the PMID has no reference list linked in PubMed, (c) the linkname (pubmed_pubmed_citedby / pubmed_pubmed_refs) yields an empty linksetdb, (d) an invalid PMID returns a linkset with no linksetdbs at all.

Common situations: Querying citations for an article published days ago (citation indexing lags months); a PMID with unlinked references; typo'd PMID producing an empty linkset; expecting references for a record whose bibliography wasn't deposited.

Related errors

• pubmed article
• pubmed author
• pubmed clinical-trial
• devto/${id}
• NO_DATA

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