jackwener/OpenCLI · error · CommandExecutionError

pubmed journal did not return an id list

Error message

pubmed journal did not return an id list

What it means

This CommandExecutionError is thrown when the PubMed ESearch response does not contain an `esearchresult.idlist` array. The library treats the NCBI response shape as a contract; if the key is missing or of the wrong type, it aborts instead of crashing later with a TypeError. This usually means the ESearch call failed or returned an unexpected body.

Source

Thrown at clis/pubmed/journal.js:52

        const sort = requireChoice(args.sort, ['relevance', 'date'], 'sort', 'relevance');
        const terms = [`${journal}[Journal]`];
        if (yearFrom || yearTo) {
            const from = yearFrom || 1800;
            const to = yearTo || new Date().getFullYear();
            if (from > to) {
                throw new ArgumentError('pubmed year-from must be <= year-to');
            }
            terms.push(`${from}:${to}[PDAT]`);
        }
        const esearch = await eutilsFetch('esearch', {
            term: terms.join(' AND '),
            retmax: limit,
            usehistory: 'y',
            sort: sort === 'date' ? 'pub_date' : '',
        }, { label: 'pubmed journal' });
        const pmids = esearch?.esearchresult?.idlist;
        if (!Array.isArray(pmids)) {
            throw new CommandExecutionError('pubmed journal did not return an id list', 'PubMed ESearch response shape may have changed.');
        }
        if (pmids.length === 0) {
            throw new EmptyResultError('pubmed journal', `No articles found for journal "${journal}".`);
        }
        return fetchSummaryRows(pmids, 'pubmed journal summary');
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Retry the command after a short delay; transient NCBI errors and rate limits are the most common cause
2. Add an NCBI API key (api_key) and throttle requests to <=3/sec to avoid rate-limit error bodies
3. Log/print the raw esearch response to inspect the actual shape before assuming a schema change
4. Update the CLI/library if NCBI changed the ESearch response schema

Example fix

// before
const pmids = esearch?.esearchresult?.idlist;
// after (defensive check + log)
if (!Array.isArray(esearch?.esearchresult?.idlist)) {
  console.error('ESearch response:', JSON.stringify(esearch).slice(0, 500));
}

const res = await eutilsFetch('esearch', params, { label: 'pubmed journal' });
const pmids = res?.esearchresult?.idlist;
if (!Array.isArray(pmids)) {
  console.error('unexpected ESearch body:', JSON.stringify(res)?.slice(0, 500));
}

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

try {
  const rows = await clis.pubmedJournal({ journal, limit });
} catch (e) {
  if (e.name === 'CommandExecutionError' && /did not return an id list/.test(e.message)) {
    await sleep(1000); // back off; retry once — often rate limiting
    return retryOrInspect(e);
  }
  throw e;
}

When it happens

Trigger: NCBI E-utilities returns an error JSON (e.g. esearchresult contains ERROR instead of idlist), a rate-limit/429 HTML body is parsed oddly, network middleware returns null/undefined for `esearch`, or the API response schema changes upstream.

Common situations: Exceeding NCBI's 3 requests/second limit without an API key; NCBI maintenance windows; HTTP 5xx responses surfacing as malformed bodies; changing response handling in eutilsFetch; expired/invalid API key producing error payloads.

Related errors

• pubmed mesh did not return an id list
• pubmed review 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/6f9cb5a44863b564. Report an issue: GitHub.