jackwener/OpenCLI · warning · EmptyResultError

npm downloads

Error message

npm downloads

What it means

Thrown by the `npm downloads` command when the npm downloads API (api.npmjs.org/downloads/range) responds successfully but returns an empty downloads array for the requested package and period. The library raises EmptyResultError instead of returning an empty list so callers get an explicit, labeled signal that the query produced no data.

Source

Thrown at clis/npm/downloads.js:50

    name: 'downloads',
    access: 'read',
    description: 'Daily download counts for an npm package over a window',
    domain: 'api.npmjs.org',
    strategy: Strategy.PUBLIC,
    browser: false,
    args: [
        { name: 'name', positional: true, required: true, help: 'npm package name (e.g. "react", "@vercel/og")' },
        { name: 'period', default: 'last-week', help: 'last-day / last-week / last-month / last-year, or YYYY-MM-DD:YYYY-MM-DD' },
    ],
    columns: ['rank', 'package', 'day', 'downloads'],
    func: async (args) => {
        const name = requirePackageName(args.name);
        const period = requirePeriod(args.period);
        const url = `${NPM_API}/downloads/range/${period}/${name}`;
        const body = await npmFetch(url, `npm downloads ${name}`);
        const days = Array.isArray(body?.downloads) ? body.downloads : [];
        if (!days.length) {
            throw new EmptyResultError('npm downloads', `npm has no download stats for "${name}" in window ${period}.`);
        }
        return days.map((row, i) => ({
            rank: i + 1,
            package: String(body.package ?? name),
            day: String(row.day ?? ''),
            downloads: row.downloads != null ? Number(row.downloads) : null,
        }));
    },
});

View on GitHub (pinned to 49907e53dc)

Solutions

1. Verify the package name is spelled exactly as on npmjs.org and exists (check https://registry.npmjs.org/<name>).
2. Use a wider period such as 'last-month' or 'last-year' instead of 'last-day' or a narrow range.
3. If the package is brand new, wait until it accumulates downloads before querying.
4. In automation, treat EmptyResultError as 'no data in window' — skip or widen the window rather than retrying the identical query.

Example fix

// before
cli.run('npm downloads', { name: 'my-new-pkg', period: 'last-day' }); // EmptyResultError
// after
const period = pkgPublishedRecently ? 'last-month' : 'last-week';
try {
  await cli.run('npm downloads', { name: 'my-new-pkg', period });
} catch (e) {
  if (e.name === 'EmptyResultError') return { downloads: 0, note: 'no data in window' };
  throw e;
}

const name = (args.name ?? '').trim();
if (!name) throw new Error('name is required');
const period = args.period ?? 'last-week';
// emptiness cannot be proven pre-call; validate inputs and handle the empty case

function hasDownloads(body) {
  return !!body && Array.isArray(body.downloads) && body.downloads.length > 0;
}

try {
  return await npmDownloads({ name, period });
} catch (e) {
  if (e.name === 'EmptyResultError') return []; // or widen the period and retry once
  throw e;
}

When it happens

Trigger: Calling the downloads command for a package with zero recorded downloads in the requested period (e.g. a brand-new, unpublished, or valid-but-obscure name), or a narrow range window before/after any downloads occurred. The HTTP call itself succeeds (2xx); this is a data-emptiness condition, not a network failure.

Common situations: Querying a package published minutes ago; typos like 'reacct' that are still valid name syntax; requesting a historical range from before the package existed; scoped names with wrong casing; low-traffic packages with no hits in 'last-day'.

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 trains found from ${fromStation.name} to ${toStation.name
• NO_DATA
• No Wayback snapshots for "${target}".
• Chess.com has no game archives for ${username}
• Chess.com has games archives for ${username} but no games in

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