jackwener/OpenCLI · error · CommandExecutionError

pubmed mesh did not return an id list

Error message

pubmed mesh did not return an id list

What it means

This CommandExecutionError is thrown when the ESearch response for the `pubmed mesh` command lacks a valid `esearchresult.idlist` array. Like the journal variant, it guards against malformed or error responses from NCBI E-utilities so downstream code never iterates undefined. It indicates the HTTP/API exchange did not yield the expected structure.

Source

Thrown at clis/pubmed/mesh.js:40

        { name: 'limit', type: 'int', default: 20, help: 'Max results (1-100)' },
        { name: 'major', type: 'boolean', default: false, help: 'Only include articles where this is a major MeSH topic' },
        { name: 'sort', default: 'relevance', choices: ['relevance', 'date'], help: 'Sort by relevance or date' },
    ],
    columns: SEARCH_COLUMNS,
    func: async (args) => {
        const term = requireText(args.term, 'term');
        const limit = requireBoundedInt(args.limit, 20, 100);
        const sort = requireChoice(args.sort, ['relevance', 'date'], 'sort', 'relevance');
        const tag = args.major ? 'Majr' : 'MeSH Terms';
        const esearch = await eutilsFetch('esearch', {
            term: `${term}[${tag}]`,
            retmax: limit,
            usehistory: 'y',
            sort: sort === 'date' ? 'pub_date' : '',
        }, { label: 'pubmed mesh' });
        const pmids = esearch?.esearchresult?.idlist;
        if (!Array.isArray(pmids)) {
            throw new CommandExecutionError('pubmed mesh did not return an id list', 'PubMed ESearch response shape may have changed.');
        }
        if (pmids.length === 0) {
            throw new EmptyResultError('pubmed mesh', `No articles found for MeSH term "${term}".`);
        }
        return fetchSummaryRows(pmids, 'pubmed mesh summary');
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Retry after a delay — transient NCBI/rate-limit failures are the most frequent cause
2. Register and use an NCBI api_key and throttle to <=3 req/sec
3. Quote/sanitize the MeSH term (e.g. 'Diabetes Mellitus, Type 2'[MeSH]) and re-run
4. Inspect the raw response body to confirm whether the API schema changed

const res = await eutilsFetch('esearch', { term: `${term}[MeSH Terms]`, retmax: 0 }, { label: 'probe' });
if (res?.esearchresult?.ERROR) console.error('ESearch error:', res.esearchresult.ERROR);
if (!res?.esearchresult) console.error('unexpected ESearch body');

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

try {
  return await clis.pubmedMesh({ term, limit });
} catch (e) {
  if (e.name === 'CommandExecutionError' && /did not return an id list/.test(e.message)) {
    await sleep(1000);
    return retryOnceOrEscalate(e); // often transient/rate-limit
  }
  throw e;
}

When it happens

Trigger: esearchresult contains an ERROR payload (e.g. invalid term quoting), rate limiting returns a non-standard body, eutilsFetch resolves with null/undefined, or the MeSH term contains characters that break the query causing an API error response.

Common situations: Unescaped special characters (quotes, ampersands) in the MeSH term; hitting NCBI rate limits without an API key; NCBI downtime; proxy or corporate firewall rewriting API responses.

Related errors

• pubmed journal 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/3108c80fb5497d7f. Report an issue: GitHub.