jackwener/OpenCLI · error · ArgumentError

archive snapshots limit must be <= 1000

Error message

archive snapshots limit must be <= 1000

What it means

ArgumentError thrown when the `limit` argument exceeds the library's hard maximum of 1000, which matches the Wayback CDX API's own per-page cap. This prevents users from requesting result counts the API cannot serve anyway.

Source

Thrown at clis/archive/snapshots.js:50

        { name: 'from', type: 'string', required: false, help: 'Earliest year/timestamp (YYYY[MM[DD[hh[mm[ss]]]]])' },
        { name: 'to', type: 'string', required: false, help: 'Latest year/timestamp (YYYY[MM[DD[hh[mm[ss]]]]])' },
        { name: 'limit', type: 'int', default: 20, help: 'Max snapshots to return (max 1000).' },
    ],
    columns: ['timestamp', 'snapshot_url', 'status', 'mimetype', 'original_url'],
    func: async (args) => {
        const target = String(args.url ?? '').trim();
        if (!target) {
            throw new ArgumentError(
                'archive snapshots url cannot be empty',
                'Example: opencli archive snapshots wikipedia.org',
            );
        }
        const limit = Number(args.limit ?? 20);
        if (!Number.isInteger(limit) || limit <= 0) {
            throw new ArgumentError('archive snapshots limit must be a positive integer');
        }
        if (limit > 1000) {
            throw new ArgumentError('archive snapshots limit must be <= 1000');
        }
        for (const key of ['from', 'to']) {
            const v = args[key];
            if (v != null && !/^\d{4,14}$/.test(String(v))) {
                throw new ArgumentError(`archive snapshots ${key} must be a digit-only timestamp (YYYY[MM[DD[hh[mm[ss]]]]])`);
            }
        }

        // Wayback CDX is served on HTTP only; the HTTPS endpoint returns 503.
        const apiUrl = new URL('http://web.archive.org/cdx/search/cdx');
        apiUrl.searchParams.set('url', target);
        apiUrl.searchParams.set('output', 'json');
        apiUrl.searchParams.set('limit', String(limit));
        if (args.from) apiUrl.searchParams.set('from', String(args.from));
        if (args.to) apiUrl.searchParams.set('to', String(args.to));

        let resp;
        try {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Cap the limit at 1000: opencli archive snapshots example.org --limit 1000
2. Paginate with CDX 'from'/'to' timestamp filters to cover more than 1000 snapshots in chunks.
3. Omit --limit to get the default 20.

Example fix

// before
opencli archive snapshots example.org --limit 5000
// after
opencli archive snapshots example.org --limit 1000

// Clamp before invoking
const clamped = Math.min(Math.max(1, Math.floor(Number(raw) || 20)), 1000);
// node
if (n > 1000) { n = 1000; console.warn('limit clamped to CDX max of 1000'); }

function isWithinLimit(v, max = 1000) {
  return Number.isInteger(v) && v > 0 && v <= max;
}

try {
  await run(['archive', 'snapshots', url, '--limit', String(limit)]);
} catch (e) {
  if (/limit must be <= 1000/.test(e.message)) {
    await run(['archive', 'snapshots', url, '--limit', '1000']);
  } else throw e;
}

When it happens

Trigger: Running `opencli archive snapshots <url> --limit 1001` (or any larger value).

Common situations: Users wanting 'all snapshots' guessing a huge number; misunderstanding limit as unlimited when set very high.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• archive snapshots url cannot be empty
• archive snapshots limit must be a positive integer
• archive snapshots ${key} must be a digit-only timestamp (YYY
• limit must be <= ${MAX_LIMIT}
• bilibili unfollow target must be a valid space.bilibili.com/

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