jackwener/OpenCLI · warning · EmptyResultError

crates search

Error message

crates search

What it means

The 'crates search' EmptyResultError is thrown when the crates.io search API returns an empty crates list for the given query. The adapter treats 'zero matches' as a distinct typed result so callers can render a friendly 'no results' message instead of an empty array or a generic error.

Source

Thrown at clis/crates/search.js:30

    name: 'search',
    access: 'read',
    description: 'Search the public crates.io registry by keyword',
    domain: 'crates.io',
    strategy: Strategy.PUBLIC,
    browser: false,
    args: [
        { name: 'query', positional: true, required: true, help: 'Search keyword (e.g. "serde", "async runtime")' },
        { name: 'limit', type: 'int', default: 20, help: 'Max results (1-100)' },
    ],
    columns: ['rank', 'name', 'latestVersion', 'description', 'downloads', 'recentDownloads', 'repository', 'updated', 'url'],
    func: async (args) => {
        const query = requireString(args.query, 'query');
        const limit = requireBoundedInt(args.limit, 20, 100);
        const url = `${CRATES_BASE}/api/v1/crates?q=${encodeURIComponent(query)}&per_page=${limit}`;
        const body = await cratesFetch(url, 'crates search');
        const list = Array.isArray(body?.crates) ? body.crates : [];
        if (!list.length) {
            throw new EmptyResultError('crates search', `No crates.io results matched "${query}".`);
        }
        return list.slice(0, limit).map((c, i) => ({
            rank: i + 1,
            name: String(c.name ?? c.id ?? ''),
            latestVersion: String(c.newest_version ?? c.max_stable_version ?? c.max_version ?? ''),
            description: String(c.description ?? '').trim(),
            downloads: c.downloads != null ? Number(c.downloads) : null,
            recentDownloads: c.recent_downloads != null ? Number(c.recent_downloads) : null,
            repository: String(c.repository ?? c.homepage ?? ''),
            updated: String(c.updated_at ?? '').slice(0, 10),
            url: c.name ? `https://crates.io/crates/${c.name}` : '',
        }));
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Broaden the query (shorter, more generic keywords).
2. Check spelling; run the same query on crates.io search in a browser to confirm zero matches.
3. If you know the exact name, use `crates crate <name>` directly instead of search.
4. Catch EmptyResultError and display 'no crates matched' rather than treating it as a failure.

Example fix

// before
const res = await cli.crates.search({ query: 'my-internal-only-crate' });
// after
const res = await cli.crates.search({ query: 'serde' }); // or handle empty:
try { ... } catch (e) { if (e instanceof EmptyResultError) show('no matches'); }

const q = (query ?? '').trim();
if (!q) throw new Error('query required');
// optionally pre-check breadth: very long or highly specific queries often return 0 hits

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

try {
  const res = await cli.crates.search({ query });
  return res;
} catch (e) {
  if (e instanceof EmptyResultError) {
    console.warn(`No crates matched "${query}"; broadening query...`);
    return cli.crates.search({ query: query.split(/\s+/)[0] }); // fall back to first keyword
  }
  throw e;
}

When it happens

Trigger: Calling `crates search <query>` with a term that matches no crates on crates.io, an overly specific query, or a misspelled keyword; requireString/query validation passed but body.crates is an empty array.

Common situations: Searching for an internal or unpublished crate name, using keywords in a language crates.io does not index, pasting a full crate URL as the query, or searching a very new crate before indexing.

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 12306 stations match "${keyword}"
• ${label}
• No papers found for author "${authorText}". Try alternate sp
• No papers found. Try a different keyword.
• crates crate

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