jackwener/OpenCLI · error · ArgumentError

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

Error message

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

What it means

requireBoundedInt enforces an upper bound on numeric arguments and throws ArgumentError when the value exceeds `maxValue`. For the OpenAlex adapter this caps `limit` because the API's `per-page` parameter has a maximum page size; larger values would be rejected or misbehave upstream. The message names both the label and the allowed maximum.

Source

Thrown at clis/openalex/utils.js:33

const WORK_ID = /^W\d{4,}$/;
// DOIs are loose — accept anything starting with "10." after the optional
// `doi.org/` prefix; OpenAlex itself does the normalization.
const DOI_BARE = /^10\.\S+$/;

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

/**
 * Resolve a user-supplied work identifier to OpenAlex's canonical path
 * segment. Accepts `W…` IDs, `doi:10.…`, raw DOIs, or full
 * `https://doi.org/…` / `https://openalex.org/W…` URLs.
 */
export function requireWorkRef(value) {
    const raw = String(value ?? '').trim();
    if (!raw) {
        throw new ArgumentError('openalex work id is required (e.g. "W2741809807", "10.7717/peerj.4375")');
    }
    // 1) full openalex URL
    const oaUrl = raw.match(/^https?:\/\/(?:api\.)?openalex\.org\/(?:works\/)?([WAaSCFwIPwT]\d+)/i);
    if (oaUrl) {
        const id = oaUrl[1].toUpperCase();

View on GitHub (pinned to 49907e53dc)

Solutions

1. Lower limit to the documented maximum (see the command's --help or maxValue)
2. Paginate using multiple requests with cursor/page instead of one oversized request
3. Clamp the value in your code: Math.min(requested, maxValue)

Example fix

// before
await search({ query, limit: 500 });
// after
const MAX = 200;
await search({ query, limit: Math.min(500, MAX) }); // or paginate

const OPENALEX_MAX_LIMIT = 200;
const limit = Math.min(Number(rawLimit) || 25, OPENALEX_MAX_LIMIT);

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

try {
  await search({ query, limit });
} catch (e) {
  if (e.name === 'ArgumentError' && /must be <=/.test(e.message)) {
    console.error(`limit exceeds API maximum (${e.message})`); process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Calling a command with `limit` greater than the configured maxValue (e.g. requesting per-page=500 when the adapter caps at 200).

Common situations: Assuming the API accepts arbitrarily large page sizes; copying a limit from another API's docs; trying to 'fetch everything' with one huge limit instead of paginating.

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

• openalex ${label} must be a positive integer
• openalex ${label} cannot be empty
• openalex work id is required (e.g. "W2741809807", "10.7717/p
• openalex work id "${value}" must be a Work (W…) ID, got "${i
• openalex work id "${value}" is not recognised

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