{"record":{"id":"3108c80fb5497d7f","repo":"jackwener/OpenCLI","slug":"pubmed-mesh-did-not-return-an-id-list","errorCode":null,"errorMessage":"pubmed mesh did not return an id list","messagePattern":"pubmed mesh did not return an id list","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/pubmed/mesh.js","lineNumber":40,"sourceCode":"        { name: 'limit', type: 'int', default: 20, help: 'Max results (1-100)' },\n        { name: 'major', type: 'boolean', default: false, help: 'Only include articles where this is a major MeSH topic' },\n        { name: 'sort', default: 'relevance', choices: ['relevance', 'date'], help: 'Sort by relevance or date' },\n    ],\n    columns: SEARCH_COLUMNS,\n    func: async (args) => {\n        const term = requireText(args.term, 'term');\n        const limit = requireBoundedInt(args.limit, 20, 100);\n        const sort = requireChoice(args.sort, ['relevance', 'date'], 'sort', 'relevance');\n        const tag = args.major ? 'Majr' : 'MeSH Terms';\n        const esearch = await eutilsFetch('esearch', {\n            term: `${term}[${tag}]`,\n            retmax: limit,\n            usehistory: 'y',\n            sort: sort === 'date' ? 'pub_date' : '',\n        }, { label: 'pubmed mesh' });\n        const pmids = esearch?.esearchresult?.idlist;\n        if (!Array.isArray(pmids)) {\n            throw new CommandExecutionError('pubmed mesh did not return an id list', 'PubMed ESearch response shape may have changed.');\n        }\n        if (pmids.length === 0) {\n            throw new EmptyResultError('pubmed mesh', `No articles found for MeSH term \"${term}\".`);\n        }\n        return fetchSummaryRows(pmids, 'pubmed mesh summary');\n    },\n});\n","sourceCodeStart":22,"sourceCodeEnd":48,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/pubmed/mesh.js#L22-L48","documentation":"This CommandExecutionError is thrown when the ESearch response for the `pubmed mesh` command lacks a valid `esearchresult.idlist` array. Like the journal variant, it guards against malformed or error responses from NCBI E-utilities so downstream code never iterates undefined. It indicates the HTTP/API exchange did not yield the expected structure.","triggerScenarios":"esearchresult contains an ERROR payload (e.g. invalid term quoting), rate limiting returns a non-standard body, eutilsFetch resolves with null/undefined, or the MeSH term contains characters that break the query causing an API error response.","commonSituations":"Unescaped special characters (quotes, ampersands) in the MeSH term; hitting NCBI rate limits without an API key; NCBI downtime; proxy or corporate firewall rewriting API responses.","solutions":["Retry after a delay — transient NCBI/rate-limit failures are the most frequent cause","Register and use an NCBI api_key and throttle to <=3 req/sec","Quote/sanitize the MeSH term (e.g. 'Diabetes Mellitus, Type 2'[MeSH]) and re-run","Inspect the raw response body to confirm whether the API schema changed"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const res = await eutilsFetch('esearch', { term: `${term}[MeSH Terms]`, retmax: 0 }, { label: 'probe' });\nif (res?.esearchresult?.ERROR) console.error('ESearch error:', res.esearchresult.ERROR);\nif (!res?.esearchresult) console.error('unexpected ESearch body');","typeGuard":"function hasIdlist(res) {\n  return Array.isArray(res?.esearchresult?.idlist);\n}","tryCatchPattern":"try {\n  return await clis.pubmedMesh({ term, limit });\n} catch (e) {\n  if (e.name === 'CommandExecutionError' && /did not return an id list/.test(e.message)) {\n    await sleep(1000);\n    return retryOnceOrEscalate(e); // often transient/rate-limit\n  }\n  throw e;\n}","preventionTips":["Validate MeSH terms against the NCBI MeSH Browser before querying","Quote terms containing commas/qualifiers correctly (e.g. 'Diabetes Mellitus, Type 2')","Use an api_key and rate-limit to <=3 req/sec","Log raw ELink/ESearch bodies to catch schema changes fast"],"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-29T12:17:43.993Z"}