jackwener/OpenCLI · error · CommandExecutionError

pubmed search did not return an id list

Error message

pubmed search did not return an id list

What it means

This CommandExecutionError is thrown when the ESearch response for the core `pubmed search` command does not include a valid `esearchresult.idlist` array. The library treats the ESearch contract (idlist always present, even if empty) as mandatory; deviation means the request effectively failed or the API changed.

Source

Thrown at clis/pubmed/search.js:68

            author: args.author,
            journal: args.journal,
            yearFrom,
            yearTo,
            articleType: args['article-type'],
            hasAbstract: args['has-abstract'],
            hasFullText: args['free-full-text'],
            humanOnly: args['humans-only'],
            englishOnly: args['english-only'],
        });
        const esearch = await eutilsFetch('esearch', {
            term: searchQuery,
            retmax: limit,
            usehistory: 'y',
            sort: sortMap[sort],
        }, { label: 'pubmed search' });
        const pmids = esearch?.esearchresult?.idlist;
        if (!Array.isArray(pmids)) {
            throw new CommandExecutionError('pubmed search did not return an id list', 'PubMed ESearch response shape may have changed.');
        }
        if (pmids.length === 0) {
            throw new EmptyResultError('pubmed search', `No articles matched "${query}".`);
        }
        return fetchSummaryRows(pmids, 'pubmed search summary');
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Retry after a short backoff — rate limiting and transient errors are the most common cause
2. Validate the query syntax (balanced quotes, correct field tags like [Author], [MeSH])
3. Register an NCBI api_key and throttle requests to <=3/sec
4. Log the raw esearch response to see the actual body and update the parser if NCBI changed the schema

Example fix

// before
clis.pubmedSearch({ query: '"machine learning AND [Title' });
// after
clis.pubmedSearch({ query: '"machine learning"[Title]' });

// Basic query sanity before hitting the API
function assertValidPubMedQuery(q) {
  const s = String(q);
  const quotes = (s.match(/"/g) || []).length;
  if (quotes % 2 !== 0) throw new Error('unbalanced quotes in query');
  if (/\[(?!\w+\])/.test(s)) console.warn('possible malformed field tag in query');
}

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

try {
  return await clis.pubmedSearch({ query, limit });
} catch (e) {
  if (e.name === 'CommandExecutionError' && /did not return an id list/.test(e.message)) {
    if (attempt < 3) { await sleep(2 ** attempt * 500); return retry(attempt + 1); }
  }
  throw e; // persistent failures: inspect raw body / schema
}

When it happens

Trigger: PubMed returns an esearchresult containing an ERROR entry (bad query syntax like unbalanced quotes/field tags), rate-limit or HTML error bodies, eutilsFetch returning null/undefined, or an upstream schema change.

Common situations: Exceeding 3 anonymous requests/second to E-utilities; invalid query syntax (e.g. `author[Auther]`, stray quotes) causing an API-side error object; NCBI outage; aggressive retry loops getting throttled.

Related errors

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