jackwener/OpenCLI · error · ArgumentError

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

Error message

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

What it means

requireBoundedInt also enforces an upper bound: after passing the positive-integer check, a value greater than maxValue throws ArgumentError(`rubygems ${label} must be <= ${maxValue}`). For rubygems search the maxValue is 100, so limit is clamped to the API's sane range rather than letting requests grow unbounded.

Source

Thrown at clis/rubygems/utils.js:28

const UA = 'opencli-rubygems-adapter (+https://github.com/jackwener/opencli)';

// RubyGems gem name pattern (mirrors the rubygems-server validation).
const GEM_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;

export function requireString(value, label) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError(`rubygems ${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(`rubygems ${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`rubygems ${label} must be <= ${maxValue}`);
    }
    return n;
}

export function requireGemName(value) {
    const s = String(value ?? '').trim();
    if (!s) {
        throw new ArgumentError('rubygems gem name is required (e.g. "rails", "sidekiq")');
    }
    if (s.length > 100 || !GEM_NAME.test(s)) {
        throw new ArgumentError(
            `rubygems gem "${value}" is not a valid gem name`,
            'Use letters / digits / "._-", starting with a letter or digit (max 100 chars).',
        );
    }
    return s;
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Lower the limit to 100 or below: `--limit 100` is the maximum for rubygems search.
2. If more results are needed, page through via multiple queries with different terms (the API only exposes page=1 here).
3. Clamp in calling code: `limit = Math.min(Number(limit) || 30, 100)` before invoking.

Example fix

// before
await search({ query: 'rails', limit: 500 }); // throws

// after
await search({ query: 'rails', limit: Math.min(500, 100) }); // 100

function clampLimit(v, max = 100, def = 30) {
  const n = v == null ? def : Number(v);
  if (!Number.isInteger(n) || n <= 0) throw new Error(`limit must be a positive integer`);
  if (n > max) throw new Error(`limit must be <= ${max}`);
  return n;
}

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

try {
  await search({ query, limit });
} catch (e) {
  if (e instanceof ArgumentError && /must be <=/.test(e.message)) {
    console.error('Max limit is 100 for rubygems search');
  } else throw e;
}

When it happens

Trigger: search({ query: 'rails', limit: 500 }) or any limit > 100; any other requireBoundedInt caller passing a value above the maxValue it was given.

Common situations: Users expecting 'give me everything' via a huge limit; scripts copying limits from other tools with different bounds; misremembering the max (e.g. trying 1000 for a top-100 API).

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

• rubygems ${label} must be a positive integer
• --limit must be a positive integer, got ${JSON.stringify(kwa
• `endoflife ${label} must be <= ${maxValue}`
• facebook search --limit must be an integer between 1 and ${M
• facebook search requires a non-empty query

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