jackwener/OpenCLI · info · EmptyResultError

No OpenAlex works matched "${query}".

Error message

No OpenAlex works matched "${query}".

What it means

This EmptyResultError is thrown when the OpenAlex /works search endpoint succeeds but returns zero results for the given query string. The library treats an empty result set as a distinct, expected condition so callers can distinguish 'no such works exist' from transport or auth failures. It embeds the original query in the message for debugging.

Source

Thrown at clis/openalex/search.js:46

    description: 'Search OpenAlex Works (papers, books, preprints) by keyword',
    domain: 'api.openalex.org',
    strategy: Strategy.PUBLIC,
    browser: false,
    args: [
        { name: 'query', positional: true, required: true, help: 'Search text (e.g. "transformers", "open access scholarly")' },
        { name: 'limit', type: 'int', default: 20, help: 'Max works (1-200, single OpenAlex page)' },
    ],
    columns: ['rank', 'id', 'title', 'year', 'citations', 'firstAuthor', 'venue', 'openAccess', 'type', 'doi', 'url'],
    func: async (args) => {
        const query = requireString(args.query, 'query');
        const limit = requireBoundedInt(args.limit, 20, 200);
        const url = appendMailto(
            `${OPENALEX_BASE}/works?search=${encodeURIComponent(query)}&per-page=${limit}&select=${SELECT_FIELDS}`,
        );
        const body = await openalexFetch(url, 'openalex search');
        const list = Array.isArray(body?.results) ? body.results : [];
        if (!list.length) {
            throw new EmptyResultError('openalex search', `No OpenAlex works matched "${query}".`);
        }
        return list.slice(0, limit).map((w, i) => {
            const firstAuthor = Array.isArray(w.authorships) && w.authorships.length
                ? String(w.authorships[0]?.author?.display_name ?? '').trim()
                : '';
            const venue = String(w.primary_location?.source?.display_name ?? '').trim();
            const id = bareId(w.id);
            return {
                rank: i + 1,
                id,
                title: String(w.title ?? '').trim(),
                year: w.publication_year != null ? Number(w.publication_year) : null,
                citations: w.cited_by_count != null ? Number(w.cited_by_count) : null,
                firstAuthor,
                venue,
                openAccess: Boolean(w.open_access?.is_oa),
                type: String(w.type ?? '').trim(),
                doi: bareDoi(w.doi),

View on GitHub (pinned to 49907e53dc)

Solutions

1. Simplify the query to a few distinctive words from the title and retry
2. Verify the work exists by searching on openalex.org directly in a browser
3. If you have a DOI or W-id, use the ref/get endpoint instead of free-text search
4. Add `mailto` (OPENALEX_MAILTO) to rule out polite-pool filtering and retry after a pause

Example fix

// before
await openalexSearch('"A highly specific quoted phrase that matches nothing"');
// after
await openalexSearch('attention is all you need');

const q = (query ?? '').trim();
if (!q) throw new Error('query must be non-empty before searching');

function isNonEmptyString(v) {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  const results = await openalexSearch(query);
} catch (e) {
  if (e.name === 'EmptyResultError') return []; // no matches, not a failure
  throw e;
}

When it happens

Trigger: Calling the openalex search command with a query string that returns an empty `body.results` array from api.openalex.org — e.g. a misspelled title, overly specific search terms, or quoted phrases OpenAlex cannot match.

Common situations: Typo'd or garbled paper titles; searching for very niche preprints not yet indexed; pasting an entire citation sentence as the query; using field names or boolean syntax OpenAlex search does not support; expecting DOI lookup behavior from the search endpoint instead of the ref resolver.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• No items match "${query}" on archive.org.
• No hotels rendered (${totalText}). Try a broader destination
• No Douyin videos matched "${keyword}".
• flathub search
• NOT_FOUND

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