jackwener/OpenCLI · error · CommandExecutionError

pubmed review did not return an id list

Error message

pubmed review did not return an id list

What it means

This CommandExecutionError is thrown when the ESearch response for `pubmed review` has no valid `esearchresult.idlist` array. The library validates the response shape before reading results, so a malformed or error body (rate limit, downtime, schema change) surfaces as this explicit error instead of a TypeError downstream.

Source

Thrown at clis/pubmed/review.js:51

        const limit = requireBoundedInt(args.limit, 20, 100);
        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: 'Review',
            hasAbstract: args['has-abstract'],
        });
        const esearch = await eutilsFetch('esearch', {
            term: searchQuery,
            retmax: limit,
            usehistory: 'y',
            sort: sort === 'date' ? 'pub_date' : '',
        }, { label: 'pubmed review' });
        const pmids = esearch?.esearchresult?.idlist;
        if (!Array.isArray(pmids)) {
            throw new CommandExecutionError('pubmed review did not return an id list', 'PubMed ESearch response shape may have changed.');
        }
        if (pmids.length === 0) {
            throw new EmptyResultError('pubmed review', `No review articles matched "${query}".`);
        }
        return fetchSummaryRows(pmids, 'pubmed review summary');
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Retry after a pause; transient API errors are the top cause
2. Add an NCBI api_key and keep to <=3 requests/second
3. Check the user query for unbalanced quotes/brackets that would make ESearch return an error object
4. Inspect the raw response to confirm whether the schema changed and update accordingly

const res = await eutilsFetch('esearch', { term, retmax: 0 }, { label: 'probe' });
if (res?.esearchresult?.ERROR) throw new Error(`bad query: ${res.esearchresult.ERROR}`);
if (!Array.isArray(res?.esearchresult?.idlist)) console.error('unexpected ESearch body');

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

try {
  return await clis.pubmedReview({ query, limit });
} catch (e) {
  if (e.name === 'CommandExecutionError' && /did not return an id list/.test(e.message)) {
    await backoff(); // retry once; escalate with raw response if it repeats
    return retryOnce();
  }
  throw e;
}

When it happens

Trigger: NCBI returns an error payload in esearchresult (invalid query syntax in the constructed review-filtered query), rate limiting, eutilsFetch resolves to null/undefined, or the ESearch response schema changes.

Common situations: Requests exceeding NCBI's anonymous rate limit; NCBI maintenance; malformed quotes/brackets in the user query that propagate into the API term; misconfigured proxy altering responses.

Related errors

• pubmed journal did not return an id list
• pubmed mesh did not return an id list
• pubmed search did not return an id list
• Bilibili ${label} API returned a malformed payload
• Bilibili ${label} API failed: ${message} (${payload.code})

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