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.

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)

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.

Related errors

• pubmed author did not return an id list
• pubmed article ${pmid} did not include a title
• API_ERROR
• API_ERROR
• Cannot resolve aid for bvid: ${bvid}

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