jackwener/OpenCLI · error · CommandExecutionError

pubmed author did not return an id list

Error message

pubmed author did not return an id list

What it means

CommandExecutionError thrown at clis/pubmed/author.js:57 when the ESearch response does not contain esearchresult.idlist as an array. The command treats this as a schema violation ('response shape may have changed') distinct from an empty result: the API answered, but not with the expected id-list structure, so the CLI cannot proceed to fetch summaries.

Source

Thrown at clis/pubmed/author.js:57

        const terms = [`${name}[${authorTag}]`];
        if (args.affiliation) terms.push(`${requireText(args.affiliation, 'affiliation')}[ad]`);
        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 author' });
        const pmids = esearch?.esearchresult?.idlist;
        if (!Array.isArray(pmids)) {
            throw new CommandExecutionError('pubmed author did not return an id list', 'PubMed ESearch response shape may have changed.');
        }
        if (pmids.length === 0) {
            throw new EmptyResultError('pubmed author', `No articles found for author "${name}".`);
        }
        return fetchSummaryRows(pmids, 'pubmed author summary');
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Log the raw esearch payload to see whether NCBI returned an ERROR message or HTML instead of JSON
2. Add an NCBI api_key to avoid rate-limit responses that break the expected shape
3. Check the E-Utils release notes for recent ESearch schema changes and update the response parsing
4. Retry with backoff if the failure coincides with heavy usage (throttling)
5. Validate the author search term is non-empty and well-formed before calling esearch

Example fix

// before
const pmids = esearch?.esearchresult?.idlist;
if (!Array.isArray(pmids)) {
    throw new CommandExecutionError('pubmed author did not return an id list', 'PubMed ESearch response shape may have changed.');
}
// after
const err = esearch?.esearchresult?.error;
if (err) {
    throw new CommandExecutionError(`pubmed esearch error: ${err}`, 'NCBI rejected the query or rate limit was hit.');
}
const pmids = esearch?.esearchresult?.idlist;
if (!Array.isArray(pmids)) {
    throw new CommandExecutionError('pubmed author did not return an id list', 'PubMed ESearch response shape may have changed.');
}

// ensure the author term is non-empty and well-formed before searching
const term = name.trim();
if (!term) throw new Error('Author name is required');
if (term.length > 300) throw new Error('Author query too long for esearch');

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

try {
  const rows = await runCli('pubmed author', { name });
} catch (e) {
  if (/did not return an id list/.test(e.message)) {
    await sleep(backoff);
    return runCli('pubmed author', { name }); // retry with api_key configured
  }
  throw e;
}

When it happens

Trigger: esearch?.esearchresult?.idlist is not an array because: (a) NCBI returned an <eSearchResult> with an ERROR element (invalid term/api key/quota), (b) the JSON/XML transform changed and idlist moved or is omitted when absent, (c) usehistory:'y' response parsing diverged, (d) an HTML error/rate-limit page was returned instead of ESearch JSON.

Common situations: Exceeding NCBI rate limits without an api_key so a throttling response replaces JSON; passing an empty author name producing an invalid term; NCBI E-Utils API changes; network proxies returning HTML error pages.

Related errors

• pubmed clinical-trial 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/fa63808b8cd2f688. Report an issue: GitHub.