{"record":{"id":"fa63808b8cd2f688","repo":"jackwener/OpenCLI","slug":"pubmed-author-did-not-return-an-id-list","errorCode":null,"errorMessage":"pubmed author did not return an id list","messagePattern":"pubmed author did not return an id list","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/pubmed/author.js","lineNumber":57,"sourceCode":"        const terms = [`${name}[${authorTag}]`];\n        if (args.affiliation) terms.push(`${requireText(args.affiliation, 'affiliation')}[ad]`);\n        if (yearFrom || yearTo) {\n            const from = yearFrom || 1800;\n            const to = yearTo || new Date().getFullYear();\n            if (from > to) {\n                throw new ArgumentError('pubmed year-from must be <= year-to');\n            }\n            terms.push(`${from}:${to}[PDAT]`);\n        }\n        const esearch = await eutilsFetch('esearch', {\n            term: terms.join(' AND '),\n            retmax: limit,\n            usehistory: 'y',\n            sort: sort === 'date' ? 'pub_date' : '',\n        }, { label: 'pubmed author' });\n        const pmids = esearch?.esearchresult?.idlist;\n        if (!Array.isArray(pmids)) {\n            throw new CommandExecutionError('pubmed author did not return an id list', 'PubMed ESearch response shape may have changed.');\n        }\n        if (pmids.length === 0) {\n            throw new EmptyResultError('pubmed author', `No articles found for author \"${name}\".`);\n        }\n        return fetchSummaryRows(pmids, 'pubmed author summary');\n    },\n});\n","sourceCodeStart":39,"sourceCodeEnd":65,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/pubmed/author.js#L39-L65","documentation":"CommandExecutionError thrown at clis/pubmed/author.js:57 when the ESearch response does not contain esearchresult.idlist as an array. The command treats this as a schema violation ('response shape may have changed') distinct from an empty result: the API answered, but not with the expected id-list structure, so the CLI cannot proceed to fetch summaries.","triggerScenarios":"esearch?.esearchresult?.idlist is not an array because: (a) NCBI returned an <eSearchResult> with an ERROR element (invalid term/api key/quota), (b) the JSON/XML transform changed and idlist moved or is omitted when absent, (c) usehistory:'y' response parsing diverged, (d) an HTML error/rate-limit page was returned instead of ESearch JSON.","commonSituations":"Exceeding NCBI rate limits without an api_key so a throttling response replaces JSON; passing an empty author name producing an invalid term; NCBI E-Utils API changes; network proxies returning HTML error pages.","solutions":["Log the raw esearch payload to see whether NCBI returned an ERROR message or HTML instead of JSON","Add an NCBI api_key to avoid rate-limit responses that break the expected shape","Check the E-Utils release notes for recent ESearch schema changes and update the response parsing","Retry with backoff if the failure coincides with heavy usage (throttling)","Validate the author search term is non-empty and well-formed before calling esearch"],"exampleFix":"// before\nconst pmids = esearch?.esearchresult?.idlist;\nif (!Array.isArray(pmids)) {\n    throw new CommandExecutionError('pubmed author did not return an id list', 'PubMed ESearch response shape may have changed.');\n}\n// after\nconst err = esearch?.esearchresult?.error;\nif (err) {\n    throw new CommandExecutionError(`pubmed esearch error: ${err}`, 'NCBI rejected the query or rate limit was hit.');\n}\nconst pmids = esearch?.esearchresult?.idlist;\nif (!Array.isArray(pmids)) {\n    throw new CommandExecutionError('pubmed author did not return an id list', 'PubMed ESearch response shape may have changed.');\n}","handlingStrategy":"retry","validationCode":"// ensure the author term is non-empty and well-formed before searching\nconst term = name.trim();\nif (!term) throw new Error('Author name is required');\nif (term.length > 300) throw new Error('Author query too long for esearch');","typeGuard":"function hasIdList(res) {\n  return Array.isArray(res?.esearchresult?.idlist);\n}","tryCatchPattern":"try {\n  const rows = await runCli('pubmed author', { name });\n} catch (e) {\n  if (/did not return an id list/.test(e.message)) {\n    await sleep(backoff);\n    return runCli('pubmed author', { name }); // retry with api_key configured\n  }\n  throw e;\n}","preventionTips":["Configure an NCBI api_key and throttle to <=3 req/s without key, 10 req/s with key","Log the raw esearch payload when this fires — usually NCBI returned an ERROR element or HTML","Retry with exponential backoff on shape violations that coincide with heavy usage","Watch E-Utils release notes for ESearch schema changes"],"tags":["api","pubmed","schema-change","rate-limit"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}