{"record":{"id":"65478b065f95c0da","repo":"jackwener/OpenCLI","slug":"pubmed-clinical-trial-did-not-return-an-id-list","errorCode":null,"errorMessage":"pubmed clinical-trial did not return an id list","messagePattern":"pubmed clinical-trial did not return an id list","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/pubmed/clinical-trial.js","lineNumber":52,"sourceCode":"        const yearFrom = requireYear(args['year-from'], 'year-from');\n        const yearTo = requireYear(args['year-to'], 'year-to');\n        const sort = requireChoice(args.sort, ['date', 'relevance'], 'sort', 'date');\n        const searchQuery = buildSearchQuery(query, {\n            yearFrom,\n            yearTo,\n            articleType: 'Clinical Trial',\n            hasFullText: args['free-full-text'],\n            humanOnly: true,\n        });\n        const esearch = await eutilsFetch('esearch', {\n            term: searchQuery,\n            retmax: limit,\n            usehistory: 'y',\n            sort: sort === 'date' ? 'pub_date' : '',\n        }, { label: 'pubmed clinical-trial' });\n        const pmids = esearch?.esearchresult?.idlist;\n        if (!Array.isArray(pmids)) {\n            throw new CommandExecutionError('pubmed clinical-trial did not return an id list', 'PubMed ESearch response shape may have changed.');\n        }\n        if (pmids.length === 0) {\n            throw new EmptyResultError('pubmed clinical-trial', `No clinical trial articles matched \"${query}\".`);\n        }\n        return fetchSummaryRows(pmids, 'pubmed clinical-trial summary');\n    },\n});\n","sourceCodeStart":34,"sourceCodeEnd":60,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/pubmed/clinical-trial.js#L34-L60","documentation":"CommandExecutionError thrown at clis/pubmed/clinical-trial.js:52 when the ESearch response for the clinical-trial query lacks esearchresult.idlist as an array. Like the author command, the CLI distinguishes a malformed response (schema violation — 'PubMed ESearch response shape may have changed') from an empty hit list, and throws this error when it cannot even read the id list.","triggerScenarios":"esearch?.esearchresult?.idlist is not an array because: (a) NCBI returned an ERROR element (invalid term, quota exceeded, missing api_key), (b) an HTML/redirect error page replaced the JSON, (c) an E-Utils schema update moved/renamed idlist, (d) the response parser (eutilsFetch with label 'pubmed clinical-trial') mis-parsed a usehistory response.","commonSituations":"Bursty scripts hitting the 3 req/s anonymous rate limit; a malformed clinical-trial query term (bad field tags/quotes); corporate proxy or captive portal returning HTML; NCBI maintenance windows returning error payloads.","solutions":["Log the raw esearch response to identify the ERROR text or non-JSON payload NCBI returned","Register and use an NCBI api_key and add request throttling to stay under rate limits","Re-check the query term syntax (field tags like [tiab], quoting) — invalid terms can yield error responses","Retry with exponential backoff if failures cluster under load","Check E-Utils release notes and update the esearchresult parsing if the schema changed"],"exampleFix":"// before\nconst pmids = esearch?.esearchresult?.idlist;\nif (!Array.isArray(pmids)) {\n    throw new CommandExecutionError('pubmed clinical-trial did not return an id list', 'PubMed ESearch response shape may have changed.');\n}\n// after\nconst errText = esearch?.esearchresult?.error;\nif (errText) {\n    throw new CommandExecutionError(`pubmed clinical-trial esearch error: ${errText}`, 'Check query term, api_key, and rate limits.');\n}\nconst pmids = esearch?.esearchresult?.idlist;\nif (!Array.isArray(pmids)) {\n    throw new CommandExecutionError('pubmed clinical-trial did not return an id list', 'PubMed ESearch response shape may have changed.');\n}","handlingStrategy":"retry","validationCode":"// check the query term is non-empty and balanced before searching\nconst q = query.trim();\nif (!q) throw new Error('Clinical-trial query is required');\nif ((q.match(/\"/g) || []).length % 2 !== 0) throw new Error('Unbalanced quotes in query');","typeGuard":"function hasIdList(res) {\n  return Array.isArray(res?.esearchresult?.idlist);\n}","tryCatchPattern":"try {\n  const rows = await runCli('pubmed clinical-trial', { query });\n} catch (e) {\n  if (/did not return an id list/.test(e.message)) {\n    await sleep(backoff);\n    return runCli('pubmed clinical-trial', { query }); // with api_key + throttling in place\n  }\n  throw e;\n}","preventionTips":["Use an NCBI api_key and enforce request pacing to avoid quota/shape-breaking responses","Inspect raw responses when this fires — look for ERROR elements or HTML bodies","Quote phrases correctly and validate field tags in the query term","Add backoff/retry wrappers around all eutils calls"],"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"}