jackwener/OpenCLI · error · CommandExecutionError

pubmed clinical-trial did not return an id list

Error message

pubmed clinical-trial did not return an id list

What it means

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.

Solutions

1. Log the raw esearch response to identify the ERROR text or non-JSON payload NCBI returned
2. Register and use an NCBI api_key and add request throttling to stay under rate limits
3. Re-check the query term syntax (field tags like [tiab], quoting) — invalid terms can yield error responses
4. Retry with exponential backoff if failures cluster under load
5. Check E-Utils release notes and update the esearchresult parsing if the schema changed

Example fix

// before
const pmids = esearch?.esearchresult?.idlist;
if (!Array.isArray(pmids)) {
    throw new CommandExecutionError('pubmed clinical-trial did not return an id list', 'PubMed ESearch response shape may have changed.');
}
// after
const errText = esearch?.esearchresult?.error;
if (errText) {
    throw new CommandExecutionError(`pubmed clinical-trial esearch error: ${errText}`, 'Check query term, api_key, and rate limits.');
}
const pmids = esearch?.esearchresult?.idlist;
if (!Array.isArray(pmids)) {
    throw new CommandExecutionError('pubmed clinical-trial did not return an id list', 'PubMed ESearch response shape may have changed.');
}

// check the query term is non-empty and balanced before searching
const q = query.trim();
if (!q) throw new Error('Clinical-trial query is required');
if ((q.match(/"/g) || []).length % 2 !== 0) throw new Error('Unbalanced quotes in query');

function hasIdList(res) {
  return Array.isArray(res?.esearchresult?.idlist);
}

try {
  const rows = await runCli('pubmed clinical-trial', { query });
} catch (e) {
  if (/did not return an id list/.test(e.message)) {
    await sleep(backoff);
    return runCli('pubmed clinical-trial', { query }); // with api_key + throttling in place
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• pubmed author did not return an id list
• pubmed article did not include a title
• API_ERROR
• API_ERROR
• API_ERROR

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/65478b065f95c0da. Report an issue: GitHub.

Appendix: source

Thrown at clis/pubmed/clinical-trial.js:52

        const yearFrom = requireYear(args['year-from'], 'year-from');
        const yearTo = requireYear(args['year-to'], 'year-to');
        const sort = requireChoice(args.sort, ['date', 'relevance'], 'sort', 'date');
        const searchQuery = buildSearchQuery(query, {
            yearFrom,
            yearTo,
            articleType: 'Clinical Trial',
            hasFullText: args['free-full-text'],
            humanOnly: true,
        });
        const esearch = await eutilsFetch('esearch', {
            term: searchQuery,
            retmax: limit,
            usehistory: 'y',
            sort: sort === 'date' ? 'pub_date' : '',
        }, { label: 'pubmed clinical-trial' });
        const pmids = esearch?.esearchresult?.idlist;
        if (!Array.isArray(pmids)) {
            throw new CommandExecutionError('pubmed clinical-trial did not return an id list', 'PubMed ESearch response shape may have changed.');
        }
        if (pmids.length === 0) {
            throw new EmptyResultError('pubmed clinical-trial', `No clinical trial articles matched "${query}".`);
        }
        return fetchSummaryRows(pmids, 'pubmed clinical-trial summary');
    },
});

View on GitHub (pinned to 49907e53dc)