{"record":{"id":"3fa8f00393003c9b","repo":"jackwener/OpenCLI","slug":"flathub-search","errorCode":null,"errorMessage":"flathub search","messagePattern":"flathub search","errorType":"exception","errorClass":"EmptyResultError","httpStatus":null,"severity":"warning","filePath":"clis/flathub/search.js","lineNumber":54,"sourceCode":"        'license',\n        'isFreeLicense',\n        'mainCategories',\n        'installsLastMonth',\n        'updatedAt',\n        'url',\n    ],\n    func: async (args) => {\n        const query = requireString(args.query, 'query');\n        const limit = requireBoundedInt(args.limit, 25, 100);\n        const url = `${FLATHUB_API_BASE}/search`;\n        const body = await flathubFetch(url, 'flathub search', {\n            method: 'POST',\n            headers: { 'content-type': 'application/json' },\n            body: JSON.stringify({ query, hitsPerPage: limit, page: 1 }),\n        });\n        const list = Array.isArray(body?.hits) ? body.hits : [];\n        if (!list.length) {\n            throw new EmptyResultError('flathub search', `No Flathub apps matched \"${query}\".`);\n        }\n        return list.slice(0, limit).map((hit, i) => {\n            const appId = typeof hit?.app_id === 'string' ? hit.app_id : null;\n            return {\n                rank: i + 1,\n                appId,\n                name: typeof hit?.name === 'string' ? hit.name : null,\n                summary: typeof hit?.summary === 'string' ? hit.summary : null,\n                developer: typeof hit?.developer_name === 'string' ? hit.developer_name : null,\n                license: typeof hit?.project_license === 'string' ? hit.project_license : null,\n                isFreeLicense: hit?.is_free_license === true,\n                // `main_categories` comes back as a string (single value) on /search, not an array.\n                mainCategories: typeof hit?.main_categories === 'string'\n                    ? hit.main_categories\n                    : joinList(hit?.main_categories),\n                installsLastMonth: typeof hit?.installs_last_month === 'number' ? hit.installs_last_month : null,\n                // /search emits `updated_at` as unix-seconds int; /appstream emits ISO strings.\n                // Normalise to ISO date here so both surfaces look consistent.","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/flathub/search.js#L36-L72","documentation":"The flathub search adapter throws EmptyResultError when the Flathub POST /search endpoint returns no hits (body.hits is empty or missing). It signals that the query executed successfully but no Flathub apps matched the given search terms, so the CLI has nothing to list.","triggerScenarios":"Calling `flathub search <query>` where the query matches zero apps in the Flathub registry, or where the API response lacks a `hits` array entirely (e.g. unexpected response shape from POST https://flathub.org/api/v2/search).","commonSituations":"Typos or overly specific search terms (e.g. 'firefox-esr nightly build'); searching for apps not packaged on Flathub (e.g. proprietary apps absent from the registry); misspelling app names; Flathub API changes that rename the hits field.","solutions":["Simplify or broaden the search query to fewer, more common keywords","Check spelling of the app name and retry","Browse https://flathub.org directly to confirm the app exists there","If the query is known-good, check whether the Flathub API response shape changed (hits field renamed)"],"exampleFix":"// before\nflathub search 'gnome calculater pro plus'\n// after\nflathub search 'calculator'","handlingStrategy":"try-catch","validationCode":"const q = (query ?? '').trim();\nif (!q) throw new Error('search query is required');","typeGuard":"function hasHits(body) {\n  return body != null && typeof body === 'object' && Array.isArray(body.hits);\n}","tryCatchPattern":"try {\n  const results = await flathubSearch(query);\n} catch (err) {\n  if (err instanceof EmptyResultError) {\n    console.log(`No Flathub apps matched \"${query}\" — try broader keywords`);\n  } else throw err;\n}","preventionTips":["Use short, common keywords rather than long descriptive queries","Verify the app exists on flathub.org before scripting around it","Treat empty results as a normal outcome, not a crash, in scripts","Re-check the API response shape if a previously working query stops returning hits"],"tags":["empty-results","search","http-api"],"backgroundTag":"empty-result-set","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}