jackwener/OpenCLI · error · ArgumentError

homebrew ${label} must be <= ${maxValue}

Error message

homebrew ${label} must be <= ${maxValue}

What it means

requireBoundedInt throws ArgumentError('homebrew <label> must be <= <maxValue>') when the numeric value is a valid positive integer but exceeds the adapter's upper bound (e.g. limit > 500 for the popular command). The cap prevents abusive or nonsensical requests.

Source

Thrown at clis/homebrew/utils.js:29

// Homebrew formula / cask tokens — letters / digits / `_-.+@` (`gcc@13`,
// `imagemagick@6`, `c++`, `0-ad`, `php-cs-fixer`).
const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._+@-]*$/;

export function requireString(value, label) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError(`homebrew ${label} cannot be empty`);
    return s;
}

export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
    const raw = value ?? defaultValue;
    const n = typeof raw === 'number' ? raw : Number(raw);
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(`homebrew ${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`homebrew ${label} must be <= ${maxValue}`);
    }
    return n;
}

export function requireToken(value, label) {
    const s = String(value ?? '').trim();
    if (!s) {
        throw new ArgumentError(`homebrew ${label} is required (e.g. "wget", "gcc@13", "firefox")`);
    }
    if (s.length > 100 || !TOKEN.test(s)) {
        throw new ArgumentError(
            `homebrew ${label} "${value}" is not a valid token`,
            'Use letters / digits / "_-.+@", starting with a letter or digit (max 100 chars).',
        );
    }
    return s;
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Lower the value to at most the documented maximum (e.g. --limit 500)
2. Paginate or fetch in chunks if more items are needed
3. Check the command's --help for the allowed range
4. Pre-clamp the value with Math.min(value, max) in scripts

Example fix

// before
await homebrewPopular({ limit: 1000 });
// after
const limit = Math.min(Number(args.limit) || 30, 500);
await homebrewPopular({ limit });

function clampLimit(raw, max = 500, def = 30) {
  const n = Number(raw ?? def);
  if (!Number.isInteger(n) || n <= 0) throw new Error('limit must be a positive integer');
  return Math.min(n, max);
}

function isWithinBound(v, max) {
  return typeof v === 'number' && Number.isInteger(v) && v > 0 && v <= max;
}

try {
  await homebrewPopular({ limit });
} catch (err) {
  if (err instanceof ArgumentError && /must be <=/.test(err.message)) {
    const max = Number(err.message.match(/<= (\d+)/)?.[1] ?? 500);
    console.error(`--limit capped at ${max}`);
    return homebrewPopular({ limit: max });
  }
  throw err;
}

When it happens

Trigger: Calling the popular/list command with --limit 1000 when the maximum is 500, or any label-specific value above its configured maxValue.

Common situations: Users trying to export the full analytics list in one call, or scripts hardcoding large page sizes from another API's conventions.

Related errors

• medium limit must be <= ${maxValue}
• limit must be <= 100
• youtube history limit must be <= ${MAX_LIMIT}
• ${label} must be <= ${maxValue}
• archive search sort must be one of ${SORT_OPTIONS.join(', ')

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