jackwener/OpenCLI · error · ArgumentError

rubygems ${label} must be a positive integer

Error message

rubygems ${label} must be a positive integer

What it means

requireBoundedInt in clis/rubygems/utils.js validates numeric options such as limit: the value (or its Number() coercion) must be an integer > 0. Otherwise it throws ArgumentError(`rubygems ${label} must be a positive integer`). The default (30 for search) is used when the option is omitted, so this only fires on an explicitly provided bad value.

Source

Thrown at clis/rubygems/utils.js:25

import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

export const GEMS_BASE = 'https://rubygems.org/api/v1';
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).',
        );
    }

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Pass a positive integer, e.g. `--limit 10`, or omit the flag to use the default of 30.
  2. Sanitize caller input before the call: coerce and validate `const n = Number.parseInt(v, 10)` and check `n > 0`.
  3. If you want 'all results', pick a large bound like limit: 100 (the maxValue) instead of 0.

Example fix

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

// after
await search({ query: 'rails', limit: 100 }); // valid upper bound
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

function isPositiveInt(v) {
  return typeof v === 'number' && Number.isInteger(v) && v > 0;
}

Try / catch

try {
  await search({ query, limit: args.limit });
} catch (e) {
  if (e instanceof ArgumentError && /positive integer/.test(e.message)) {
    console.error('Use --limit <n> with n >= 1');
  } else throw e;
}

Prevention

When it happens

Trigger: Calling search({ query: 'rails', limit: 0 }), limit: -5, limit: 'ten', limit: 2.5, or limit: NaN — any explicitly passed limit that is not a positive integer.

Common situations: Users typing `--limit 0` expecting 'unlimited'; passing a numeric string with trailing spaces or locale formatting ('1,000'); a config file supplying a float or non-numeric limit.

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/9dbc446c06f31054. Report an issue: GitHub.