jackwener/OpenCLI · warning · EmptyResultError

flathub search

Error message

flathub search

What it means

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.

Source

Thrown at clis/flathub/search.js:54

        'license',
        'isFreeLicense',
        'mainCategories',
        'installsLastMonth',
        'updatedAt',
        'url',
    ],
    func: async (args) => {
        const query = requireString(args.query, 'query');
        const limit = requireBoundedInt(args.limit, 25, 100);
        const url = `${FLATHUB_API_BASE}/search`;
        const body = await flathubFetch(url, 'flathub search', {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify({ query, hitsPerPage: limit, page: 1 }),
        });
        const list = Array.isArray(body?.hits) ? body.hits : [];
        if (!list.length) {
            throw new EmptyResultError('flathub search', `No Flathub apps matched "${query}".`);
        }
        return list.slice(0, limit).map((hit, i) => {
            const appId = typeof hit?.app_id === 'string' ? hit.app_id : null;
            return {
                rank: i + 1,
                appId,
                name: typeof hit?.name === 'string' ? hit.name : null,
                summary: typeof hit?.summary === 'string' ? hit.summary : null,
                developer: typeof hit?.developer_name === 'string' ? hit.developer_name : null,
                license: typeof hit?.project_license === 'string' ? hit.project_license : null,
                isFreeLicense: hit?.is_free_license === true,
                // `main_categories` comes back as a string (single value) on /search, not an array.
                mainCategories: typeof hit?.main_categories === 'string'
                    ? hit.main_categories
                    : joinList(hit?.main_categories),
                installsLastMonth: typeof hit?.installs_last_month === 'number' ? hit.installs_last_month : null,
                // /search emits `updated_at` as unix-seconds int; /appstream emits ISO strings.
                // Normalise to ISO date here so both surfaces look consistent.

View on GitHub (pinned to 49907e53dc)

Solutions

1. Simplify or broaden the search query to fewer, more common keywords
2. Check spelling of the app name and retry
3. Browse https://flathub.org directly to confirm the app exists there
4. If the query is known-good, check whether the Flathub API response shape changed (hits field renamed)

Example fix

// before
flathub search 'gnome calculater pro plus'
// after
flathub search 'calculator'

const q = (query ?? '').trim();
if (!q) throw new Error('search query is required');

function hasHits(body) {
  return body != null && typeof body === 'object' && Array.isArray(body.hits);
}

try {
  const results = await flathubSearch(query);
} catch (err) {
  if (err instanceof EmptyResultError) {
    console.log(`No Flathub apps matched "${query}" — try broader keywords`);
  } else throw err;
}

When it happens

Trigger: 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).

Common situations: 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.

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}".
• NOT_FOUND
• No OpenAlex works matched "${query}".

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