jackwener/OpenCLI · info · EmptyResultError

pubmed clinical-trial

Error message

pubmed clinical-trial

What it means

EmptyResultError('pubmed clinical-trial') thrown at clis/pubmed/clinical-trial.js:55 when ESearch returned a valid idlist array with zero entries — no PubMed clinical-trial articles match the query. This is the expected 'no hits' signal: the API worked, the search simply matched nothing.

Source

Thrown at clis/pubmed/clinical-trial.js:55

        const searchQuery = buildSearchQuery(query, {
            yearFrom,
            yearTo,
            articleType: 'Clinical Trial',
            hasFullText: args['free-full-text'],
            humanOnly: true,
        });
        const esearch = await eutilsFetch('esearch', {
            term: searchQuery,
            retmax: limit,
            usehistory: 'y',
            sort: sort === 'date' ? 'pub_date' : '',
        }, { label: 'pubmed clinical-trial' });
        const pmids = esearch?.esearchresult?.idlist;
        if (!Array.isArray(pmids)) {
            throw new CommandExecutionError('pubmed clinical-trial did not return an id list', 'PubMed ESearch response shape may have changed.');
        }
        if (pmids.length === 0) {
            throw new EmptyResultError('pubmed clinical-trial', `No clinical trial articles matched "${query}".`);
        }
        return fetchSummaryRows(pmids, 'pubmed clinical-trial summary');
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Broaden the query: drop quotes, field tags, and secondary filters; search just the drug or condition name
  2. Check spelling and use MeSH terms (e.g. "Diabetes Mellitus, Type 2"[MeSH]) instead of free text
  3. Remove the date/sort restrictions and re-run, then narrow incrementally
  4. Verify in the PubMed web UI that the same query returns hits; if not, adjust the term construction in the CLI args
  5. If you need trial registries rather than publications, query ClinicalTrials.gov API instead

Example fix

// before
await runCli('pubmed clinical-trial "\"novel compound XYZ-42\""', { 'year-from': 2025, sort: 'date' });
// after
await runCli('pubmed clinical-trial "XYZ-42"', {}); // broaden first, then add filters back gradually
Defensive patterns

Strategy: try-catch

Validate before calling

// broad pre-check: confirm the primary term has any PubMed hits before narrowing
const probe = await runCli('pubmed esearch', { term: primaryTerm, retmax: 1 });
if (!probe || probe.length === 0) console.warn(`No PubMed hits at all for "${primaryTerm}" — broaden the query`);

Try / catch

try {
  const rows = await runCli('pubmed clinical-trial', { query });
} catch (e) {
  if (e instanceof EmptyResultError || /No clinical trial articles matched/.test(e.message)) {
    console.warn(`No clinical-trial hits for "${query}" — broaden terms or use MeSH headings.`);
    return [];
  }
  throw e;
}

Prevention

When it happens

Trigger: esearchresult.idlist is an array of length 0 because: (a) the query terms are too narrow (rare condition + restrictive date/field filters), (b) misspelled drug/condition terms, (c) sort=pub_date combined with filters that exclude everything, (d) the query uses field tags that don't apply to clinical-trial publication types.

Common situations: Searching an investigational drug with no published trial results; quoting the whole query so it becomes an exact phrase; adding [title] field filters that miss abstract-only records; expecting trial registry entries (ClinicalTrials.gov) that PubMed does not index.

Related errors

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