{"record":{"id":"68c47f0746aeb0f8","repo":"jackwener/OpenCLI","slug":"pubmed-citations","errorCode":null,"errorMessage":"pubmed citations","messagePattern":"pubmed citations","errorType":"exception","errorClass":"EmptyResultError","httpStatus":null,"severity":"info","filePath":"clis/pubmed/citations.js","lineNumber":32,"sourceCode":"        { name: 'pmid', positional: true, required: true, help: 'PubMed ID, e.g. 37780221' },\n        { name: 'direction', default: 'citedby', choices: ['citedby', 'references'], help: 'citedby or references' },\n        { name: 'limit', type: 'int', default: 20, help: 'Max results (1-100)' },\n    ],\n    columns: LINK_COLUMNS,\n    func: async (args) => {\n        const pmid = requirePmid(args.pmid);\n        const direction = requireChoice(args.direction, ['citedby', 'references'], 'direction', 'citedby');\n        const limit = requireBoundedInt(args.limit, 20, 100);\n        const linkname = direction === 'citedby' ? 'pubmed_pubmed_citedin' : 'pubmed_pubmed_refs';\n        const result = await eutilsFetch('elink', {\n            id: pmid,\n            dbfrom: 'pubmed',\n            cmd: 'neighbor',\n            linkname,\n        }, { label: 'pubmed citations' });\n        const links = result?.linksets?.[0]?.linksetdbs?.[0]?.links;\n        if (!Array.isArray(links) || links.length === 0) {\n            throw new EmptyResultError('pubmed citations', `No ${direction} links found for PMID ${pmid}.`);\n        }\n        return fetchSummaryRows(links.slice(0, limit).map(String), 'pubmed citations summary');\n    },\n});\n","sourceCodeStart":14,"sourceCodeEnd":37,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/pubmed/citations.js#L14-L37","documentation":"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.","triggerScenarios":"(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.","commonSituations":"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.","solutions":["Verify the PMID exists and check its citation count on the PubMed website before scripting","For recent papers, wait — cited-by indexing lags publication by weeks/months","Try the opposite direction (references vs cited-by) to see if the record has any links","If you have a DOI, confirm the PMID mapping first (esearch) so you aren't querying a dead id","Treat this as an expected empty state in your tooling rather than retrying aggressively"],"exampleFix":"// before\nconst links = result?.linksets?.[0]?.linksetdbs?.[0]?.links;\nif (!Array.isArray(links) || links.length === 0) {\n    throw new EmptyResultError('pubmed citations', `No ${direction} links found for PMID ${pmid}.`);\n}\n// after\nconst links = result?.linksets?.[0]?.linksetdbs?.[0]?.links ?? [];\nif (links.length === 0) {\n    console.warn(`No ${direction} links for PMID ${pmid}; the article may be too new or unlinked.`);\n    return [];\n}","handlingStrategy":"fallback","validationCode":"// resolve the PMID and its existence first via esearch\nconst hit = await runCli('pubmed esearch', { term: `${pmid}[uid]` });\nif (!hit || hit.length === 0) throw new Error(`PMID ${pmid} not found in PubMed`);","typeGuard":null,"tryCatchPattern":"try {\n  const cites = await runCli('pubmed citations', { pmid, direction });\n} catch (e) {\n  if (e instanceof EmptyResultError || /No .* links found/.test(e.message)) {\n    console.warn(`PMID ${pmid} has no ${direction} links yet — returning empty set.`);\n    return [];\n  }\n  throw e;\n}","preventionTips":["Expect zero citations for articles published in the last few months; build lag into pipelines","Check both directions (cited-by and references) before concluding no data exists","Validate PMIDs via esearch before elink calls","Return empty arrays instead of retrying aggressively for legitimately empty linksets"],"tags":["api","pubmed","empty-result","citations"],"backgroundTag":"empty-result","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}