{"record":{"id":"fed59751b7e46d30","repo":"jackwener/OpenCLI","slug":"no-openalex-works-matched-query","errorCode":null,"errorMessage":"No OpenAlex works matched \"${query}\".","messagePattern":"No OpenAlex works matched \"(.+?)\"\\.","errorType":"exception","errorClass":"EmptyResultError","httpStatus":null,"severity":"info","filePath":"clis/openalex/search.js","lineNumber":46,"sourceCode":"    description: 'Search OpenAlex Works (papers, books, preprints) by keyword',\n    domain: 'api.openalex.org',\n    strategy: Strategy.PUBLIC,\n    browser: false,\n    args: [\n        { name: 'query', positional: true, required: true, help: 'Search text (e.g. \"transformers\", \"open access scholarly\")' },\n        { name: 'limit', type: 'int', default: 20, help: 'Max works (1-200, single OpenAlex page)' },\n    ],\n    columns: ['rank', 'id', 'title', 'year', 'citations', 'firstAuthor', 'venue', 'openAccess', 'type', 'doi', 'url'],\n    func: async (args) => {\n        const query = requireString(args.query, 'query');\n        const limit = requireBoundedInt(args.limit, 20, 200);\n        const url = appendMailto(\n            `${OPENALEX_BASE}/works?search=${encodeURIComponent(query)}&per-page=${limit}&select=${SELECT_FIELDS}`,\n        );\n        const body = await openalexFetch(url, 'openalex search');\n        const list = Array.isArray(body?.results) ? body.results : [];\n        if (!list.length) {\n            throw new EmptyResultError('openalex search', `No OpenAlex works matched \"${query}\".`);\n        }\n        return list.slice(0, limit).map((w, i) => {\n            const firstAuthor = Array.isArray(w.authorships) && w.authorships.length\n                ? String(w.authorships[0]?.author?.display_name ?? '').trim()\n                : '';\n            const venue = String(w.primary_location?.source?.display_name ?? '').trim();\n            const id = bareId(w.id);\n            return {\n                rank: i + 1,\n                id,\n                title: String(w.title ?? '').trim(),\n                year: w.publication_year != null ? Number(w.publication_year) : null,\n                citations: w.cited_by_count != null ? Number(w.cited_by_count) : null,\n                firstAuthor,\n                venue,\n                openAccess: Boolean(w.open_access?.is_oa),\n                type: String(w.type ?? '').trim(),\n                doi: bareDoi(w.doi),","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/openalex/search.js#L28-L64","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Simplify the query to a few distinctive words from the title and retry","Verify the work exists by searching on openalex.org directly in a browser","If you have a DOI or W-id, use the ref/get endpoint instead of free-text search","Add `mailto` (OPENALEX_MAILTO) to rule out polite-pool filtering and retry after a pause"],"exampleFix":"// before\nawait openalexSearch('\"A highly specific quoted phrase that matches nothing\"');\n// after\nawait openalexSearch('attention is all you need');","handlingStrategy":"try-catch","validationCode":"const q = (query ?? '').trim();\nif (!q) throw new Error('query must be non-empty before searching');","typeGuard":"function isNonEmptyString(v) {\n  return typeof v === 'string' && v.trim().length > 0;\n}","tryCatchPattern":"try {\n  const results = await openalexSearch(query);\n} catch (e) {\n  if (e.name === 'EmptyResultError') return []; // no matches, not a failure\n  throw e;\n}","preventionTips":["Reduce queries to 3-6 distinctive title words","Verify rare works exist on openalex.org before scripting lookups","Use ref/DOI lookup instead of free-text search when you have an identifier"],"tags":["openalex","empty-results","search"],"backgroundTag":"empty-result-set","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}