{"record":{"id":"6f9cb5a44863b564","repo":"jackwener/OpenCLI","slug":"pubmed-journal-did-not-return-an-id-list","errorCode":null,"errorMessage":"pubmed journal did not return an id list","messagePattern":"pubmed journal did not return an id list","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/pubmed/journal.js","lineNumber":52,"sourceCode":"        const sort = requireChoice(args.sort, ['relevance', 'date'], 'sort', 'relevance');\n        const terms = [`${journal}[Journal]`];\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 journal' });\n        const pmids = esearch?.esearchresult?.idlist;\n        if (!Array.isArray(pmids)) {\n            throw new CommandExecutionError('pubmed journal did not return an id list', 'PubMed ESearch response shape may have changed.');\n        }\n        if (pmids.length === 0) {\n            throw new EmptyResultError('pubmed journal', `No articles found for journal \"${journal}\".`);\n        }\n        return fetchSummaryRows(pmids, 'pubmed journal summary');\n    },\n});\n","sourceCodeStart":34,"sourceCodeEnd":60,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/pubmed/journal.js#L34-L60","documentation":"This CommandExecutionError is thrown when the PubMed ESearch response does not contain an `esearchresult.idlist` array. The library treats the NCBI response shape as a contract; if the key is missing or of the wrong type, it aborts instead of crashing later with a TypeError. This usually means the ESearch call failed or returned an unexpected body.","triggerScenarios":"NCBI E-utilities returns an error JSON (e.g. esearchresult contains ERROR instead of idlist), a rate-limit/429 HTML body is parsed oddly, network middleware returns null/undefined for `esearch`, or the API response schema changes upstream.","commonSituations":"Exceeding NCBI's 3 requests/second limit without an API key; NCBI maintenance windows; HTTP 5xx responses surfacing as malformed bodies; changing response handling in eutilsFetch; expired/invalid API key producing error payloads.","solutions":["Retry the command after a short delay; transient NCBI errors and rate limits are the most common cause","Add an NCBI API key (api_key) and throttle requests to <=3/sec to avoid rate-limit error bodies","Log/print the raw esearch response to inspect the actual shape before assuming a schema change","Update the CLI/library if NCBI changed the ESearch response schema"],"exampleFix":"// before\nconst pmids = esearch?.esearchresult?.idlist;\n// after (defensive check + log)\nif (!Array.isArray(esearch?.esearchresult?.idlist)) {\n  console.error('ESearch response:', JSON.stringify(esearch).slice(0, 500));\n}","handlingStrategy":"try-catch","validationCode":"const res = await eutilsFetch('esearch', params, { label: 'pubmed journal' });\nconst pmids = res?.esearchresult?.idlist;\nif (!Array.isArray(pmids)) {\n  console.error('unexpected ESearch body:', JSON.stringify(res)?.slice(0, 500));\n}","typeGuard":"function hasIdlist(res) {\n  return Array.isArray(res?.esearchresult?.idlist);\n}","tryCatchPattern":"try {\n  const rows = await clis.pubmedJournal({ journal, limit });\n} catch (e) {\n  if (e.name === 'CommandExecutionError' && /did not return an id list/.test(e.message)) {\n    await sleep(1000); // back off; retry once — often rate limiting\n    return retryOrInspect(e);\n  }\n  throw e;\n}","preventionTips":["Add an NCBI api_key and throttle to <=3 requests/second","Wrap eutilsFetch calls with logging of raw bodies to detect schema drift early","Distinguish empty results (EmptyResultError) from failed requests (this error) in your retry logic","Pin/monitor the library version and check NCBI release notes for ESearch changes"],"tags":["network","api-response","pubmed","schema-change"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}