{"record":{"id":"d0644fb969a391f0","repo":"jackwener/OpenCLI","slug":"pubmed-related","errorCode":null,"errorMessage":"pubmed related","messagePattern":"pubmed related","errorType":"exception","errorClass":"EmptyResultError","httpStatus":null,"severity":"info","filePath":"clis/pubmed/related.js","lineNumber":30,"sourceCode":"    browser: false,\n    args: [\n        { name: 'pmid', positional: true, required: true, help: 'PubMed ID, e.g. 37780221' },\n        { name: 'limit', type: 'int', default: 20, help: 'Max results (1-100)' },\n        { name: 'score', type: 'boolean', default: false, help: 'Show similarity scores when available' },\n    ],\n    columns: RELATED_COLUMNS,\n    func: async (args) => {\n        const pmid = requirePmid(args.pmid);\n        const limit = requireBoundedInt(args.limit, 20, 100);\n        const result = await eutilsFetch('elink', {\n            id: pmid,\n            dbfrom: 'pubmed',\n            cmd: 'neighbor_score',\n            linkname: 'pubmed_pubmed',\n        }, { label: 'pubmed related' });\n        const rawLinks = result?.linksets?.[0]?.linksetdbs?.[0]?.links;\n        if (!Array.isArray(rawLinks) || rawLinks.length === 0) {\n            throw new EmptyResultError('pubmed related', `No related articles found for PMID ${pmid}.`);\n        }\n        const links = rawLinks\n            .map(link => typeof link === 'string' ? { id: link, score: null } : { id: String(link?.id ?? ''), score: Number.isFinite(Number(link?.score)) ? Number(link.score) : null })\n            .filter(link => link.id && link.id !== pmid)\n            .slice(0, limit);\n        if (links.length === 0) {\n            throw new EmptyResultError('pubmed related', `No related articles found for PMID ${pmid}.`);\n        }\n        const rows = await fetchSummaryRows(links.map(link => link.id), 'pubmed related summary');\n        return rows.map((row, index) => ({\n            ...row,\n            score: args.score ? links[index].score : null,\n        }));\n    },\n});\n","sourceCodeStart":12,"sourceCodeEnd":46,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/pubmed/related.js#L12-L46","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Verify the PMID exists and is a PubMed article before asking for related items\nconst sum = await eutilsFetch('esummary', { db: 'pubmed', id: pmid }, { label: 'probe' });\nif (!sum?.result?.[String(pmid)]) console.warn(`PMID ${pmid} not found — related lookup will likely be empty`);","typeGuard":"function hasRawLinks(res) {\n  const links = res?.linksets?.[0]?.linksetdbs?.[0]?.links;\n  return Array.isArray(links) && links.length > 0;\n}","tryCatchPattern":"try {\n  return await clis.pubmedRelated({ pmid, limit });\n} catch (e) {\n  if (e.name === 'EmptyResultError' && e.scope === 'pubmed related') {\n    return []; // no neighbors yet — render empty state\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["empty-result","elink","pubmed","pmid"],"backgroundTag":"empty-search-result","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}