jackwener/OpenCLI · error · CommandExecutionError

${label} returned an error

Error message

${label} returned an error

What it means

assertNoEutilsError inspects a parsed E-utilities JSON payload for NCBI's error shapes: a top-level `error` field or `esearchresult.errorlist.phrasesnotfound` / `fieldsnotfound`. If any is present it throws `${label} returned an error` with the joined messages as detail. The library throws this to surface semantic API errors that still arrive with HTTP 200.

Source

Thrown at clis/pubmed/utils.js:130

        const json = await response.json();
        assertNoEutilsError(json, label);
        return json;
    }
    catch (error) {
        if (error instanceof CommandExecutionError) {
            throw error;
        }
        const detail = error instanceof Error ? error.message : String(error);
        throw new CommandExecutionError(`${label} returned invalid JSON`, detail);
    }
}

export function assertNoEutilsError(json, label = 'PubMed E-utilities') {
    const error = json?.error
        || json?.esearchresult?.errorlist?.phrasesnotfound?.join(', ')
        || json?.esearchresult?.errorlist?.fieldsnotfound?.join(', ');
    if (error) {
        throw new CommandExecutionError(`${label} returned an error`, String(error));
    }
}

export function buildPubMedUrl(pmid) {
    return `https://pubmed.ncbi.nlm.nih.gov/${pmid}/`;
}

export function decodeXmlEntities(value) {
    return String(value ?? '')
        .replace(/&/g, '&')
        .replace(/&lt;/g, '<')
        .replace(/&gt;/g, '>')
        .replace(/&quot;/g, '"')
        .replace(/&apos;/g, "'")
        .replace(/&#39;/g, "'")
        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10)));
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Read the `detail` on the error — it contains the exact NCBI message (e.g. which phrase or field was not found)
2. Fix the query syntax or field tags in the search term
3. Remove or simplify quoted phrases that match no documents
4. Test the same query manually on pubmed.ncbi.nlm.nih.gov to validate syntax

Example fix

// before
const rows = await searchQuery('Smith J[Authr]'); // typo
// after
const rows = await searchQuery('Smith J[Author]');

// Pre-validate query field tags and quoted phrases
function validateQuery(q) {
  const badTag = /\[(?!Author|Journal|Title|Abstract|PDAT|PT|Affiliation)[^\]]+\]/i.exec(q);
  if (badTag) throw new Error(`Suspicious field tag: ${badTag[0]}`);
}

function isEutilsError(json) {
  return Boolean(json?.error
    || json?.esearchresult?.errorlist?.phrasesnotfound?.length
    || json?.esearchresult?.errorlist?.fieldsnotfound?.length);
}

try {
  const json = await esearch(query);
} catch (e) {
  if (/returned an error/.test(e.message)) {
    console.error('NCBI says:', e.detail); // fix query per detail
  }
  throw e;
}

When it happens

Trigger: Calling esearch (via eutilsFetch) when NCBI rejects the query: an unrecognized search field, a query phrase that matches nothing (phrasesnotfound), an invalid field name, or an API-level error object in the JSON body.

Common situations: Typos in PubMed field tags like [Authr] instead of [Author]; quoted phrases with zero matches; malformed query syntax passed by the user; NCBI deprecating a search field.

Related errors

• ${label} returned invalid JSON
• ${commandLabel} returned an unreadable summary payload
• ${commandLabel} omitted summaries for one or more PMIDs
• ${probe.detail}
• Bilibili creator comparison API failed: ${message} (${payloa

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