jackwener/OpenCLI · error · ArgumentError

archive snapshots limit must be a positive integer

Error message

archive snapshots limit must be a positive integer

What it means

ArgumentError thrown when the `limit` argument for `opencli archive snapshots` is not an integer greater than 0. The default is 20, so this fires only when the user explicitly passes a bad limit such as 0, a negative number, or a non-integer. It is client-side validation before any network call.

Source

Thrown at clis/archive/snapshots.js:47

    browser: false,
    args: [
        { name: 'url', positional: true, required: true, help: 'URL to look up (with or without scheme).' },
        { 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));

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Pass a positive integer: opencli archive snapshots wikipedia.org --limit 50
  2. Omit --limit entirely to use the default of 20.
  3. In scripts, sanitize the value: LIMIT=$(( ${LIMIT:-20} > 0 ? ${LIMIT:-20} : 20 )).

Example fix

// before
opencli archive snapshots example.org --limit 0
// after
opencli archive snapshots example.org --limit 20
Defensive patterns

Strategy: validation

Validate before calling

// shell
LIMIT=${LIMIT:-20}
case "$LIMIT" in ''|*[!0-9]*) echo "limit must be a positive integer" >&2; exit 1;; esac
[ "$LIMIT" -gt 0 ] || { echo "limit must be positive" >&2; exit 1; }
opencli archive snapshots "$URL" --limit "$LIMIT"
// node
const n = Number(raw);
if (!Number.isInteger(n) || n <= 0) throw new Error('limit must be a positive integer');

Type guard

function isPositiveInt(v) {
  return Number.isInteger(v) && v > 0;
}

Try / catch

try {
  await run(['archive', 'snapshots', url, '--limit', String(limit)]);
} catch (e) {
  if (/limit must be a positive integer/.test(e.message)) {
    limit = 20; // fall back to default and retry
  } else throw e;
}

Prevention

When it happens

Trigger: Running `opencli archive snapshots <url> --limit 0`, a negative value, or a non-integer (e.g. --limit 1.5 or --limit abc that coerces to NaN).

Common situations: Shell variables expanding to empty or garbage; copy-pasting a limit with units ('50 results'); confusing limit 0 with 'unlimited'.

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

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