jackwener/OpenCLI · error · ArgumentError

flathub ${label} must be a positive integer

Error message

flathub ${label} must be a positive integer

What it means

requireBoundedInt validates that a numeric option (labelled, default 'limit') is a positive integer; it throws ArgumentError with 'flathub <label> must be a positive integer' when the value is not an integer or is <= 0. This guards the limit/pagination option before it is sent to the Flathub API.

Source

Thrown at clis/flathub/utils.js:27

export const FLATHUB_API_BASE = 'https://flathub.org/api/v2';
export const FLATHUB_APP_BASE = 'https://flathub.org/apps';
const UA = 'opencli-flathub-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';

// AppStream IDs are reverse-DNS (e.g. "org.gnome.Calculator"); the spec allows
// letters, digits, `.`, `_`, `-`. Min two segments separated by `.`.
const APP_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/;

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

export function requireAppId(value) {
    const raw = String(value ?? '').trim();
    if (!raw) throw new ArgumentError('flathub appId is required (e.g. "org.mozilla.firefox")');
    if (!APP_ID_PATTERN.test(raw)) {
        throw new ArgumentError(
            `flathub appId "${value}" is not a valid AppStream identifier`,
            'AppStream IDs use reverse-DNS like "org.mozilla.firefox" — letters/digits/`._-` with at least one dot.',
        );
    }
    return raw;
}

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Pass a positive integer for the option (e.g. --limit 10)
  2. Use the default by omitting the option entirely
  3. Coerce/validate the value with Number.isInteger(Number(v)) && v > 0 before calling
  4. Fix typos or string values in the config or shell variable

Example fix

// before
await searchApps(query, { limit: 'ten' });
// after
await searchApps(query, { limit: 10 });
Defensive patterns

Strategy: validation

Validate before calling

function isValidLimit(v) {
  const n = typeof v === 'number' ? v : Number(v);
  return Number.isInteger(n) && n > 0;
}
if (!isValidLimit(opts.limit)) throw new Error('limit must be a positive integer');

Type guard

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

Try / catch

try {
  await searchApps(query, { limit });
} catch (err) {
  if (err instanceof ArgumentError && /positive integer/.test(err.message)) {
    console.error('Bad --limit value; use a positive integer like 10');
    process.exitCode = 2;
  } else throw err;
}

Prevention

When it happens

Trigger: Passing a limit of 0, a negative number, a non-integer float (e.g. 2.5), or a string that fails Number() conversion (NaN), such as requireBoundedInt('abc', 10, 50) or requireBoundedInt(0, 10, 50).

Common situations: CLI invoked with --limit 0 or a typo like --limit 1o; config file holding a string like 'ten'; parsing user input without validation; JSON config where the value is a float.

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/80796e4d099eac35. Report an issue: GitHub.