jackwener/OpenCLI · error · ArgumentError

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

Error message

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

What it means

requireBoundedInt enforces an upper bound on a numeric option (labelled, default 'limit'); it throws ArgumentError with 'flathub <label> must be <= <maxValue>' when the value is a positive integer but exceeds the adapter's allowed maximum. This keeps requests within sensible API page sizes.

Source

Thrown at clis/flathub/utils.js:30

// 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;
}

export async function flathubFetch(url, label, init) {
    let resp;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Lower the value to at most the stated maximum (the error message tells you the cap)
2. Omit the option to use the default limit
3. Paginate: fetch multiple pages instead of one oversized request
4. Clamp in your script: limit = Math.min(requested, maxAllowed)

Example fix

// before
await searchApps(query, { limit: 200 }); // max is 50
// after
await searchApps(query, { limit: Math.min(200, 50) });

const MAX_LIMIT = 50;
const limit = Math.min(Number(opts.limit ?? 10), MAX_LIMIT);
if (!Number.isInteger(limit) || limit <= 0) throw new Error('limit must be a positive integer');

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

try {
  await searchApps(query, { limit });
} catch (err) {
  if (err instanceof ArgumentError && /must be <=/.test(err.message)) {
    console.error(err.message + ' — lower the limit or paginate');
    process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Calling requireBoundedInt(value, defaultValue, maxValue, label) with a value greater than maxValue, e.g. requireBoundedInt(100, 10, 50) or a CLI invocation like `flathub search foo --limit 200` when the cap is 50.

Common situations: Users asking for very large result sets (e.g. --limit 1000); scripting with an unbounded page size; copying a limit from another API with a higher cap; misreading the documented maximum.

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

• 1688 item expects an offer URL or offer ID
• Invalid 1688 URL
• tid must be a numeric thread id
• kind
• direction

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