jackwener/OpenCLI · error · ArgumentError

${label} must be a non-negative integer

Error message

${label} must be a non-negative integer

What it means

requireNonNegativeInt coerces its input with Number() and requires an integer >= 0, throwing ArgumentError otherwise. It validates the `--page-offset` option for Suno pagination, so zero is allowed but negatives, fractions, and non-numeric values are rejected.

Source

Thrown at clis/suno/utils.js:96

export function unwrapEvaluateResult(value) {
    if (value && typeof value === 'object' && 'session' in value && 'data' in value) {
        return value.data;
    }
    return value;
}

export function requirePositiveInt(value, label) {
    const n = Number(value);
    if (!Number.isInteger(n) || n < 1) {
        throw new ArgumentError(`${label} must be a positive integer`);
    }
    return n;
}

export function requireNonNegativeInt(value, label) {
    const n = Number(value);
    if (!Number.isInteger(n) || n < 0) {
        throw new ArgumentError(`${label} must be a non-negative integer`);
    }
    return n;
}

export function clampSlider(value, label, def) {
    if (value === undefined || value === null || value === '') return def;
    const n = Number(value);
    if (!Number.isFinite(n) || n < 0 || n > 1) {
        throw new ArgumentError(`${label} must be a number between 0 and 1`);
    }
    return n;
}

// ─────────────────────────────────────────────────────────────────────────────
// In-page helper snippets. Each is inlined into a page.evaluate() call so
// the browser-token is generated fresh per request and the Clerk token is
// pulled live (avoiding 60s TTL expiry on long polls).
// ─────────────────────────────────────────────────────────────────────────────

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Use a whole number >= 0; offset 0 is the first page.
  2. Default: omit the flag entirely when you want the first page.
  3. Fix the shell variable so it expands to a valid non-negative integer (e.g. `PAGE=${PAGE:-0}`).
  4. Check the label in the error message to identify the offending flag.

Example fix

// before
opencli suno list --page-offset -1
// after
opencli suno list --page-offset 0
Defensive patterns

Strategy: validation

Validate before calling

function isNonNegativeInt(v) { const n = Number(v); return Number.isInteger(n) && n >= 0; }
if (!isNonNegativeInt(pageOffset)) throw new Error('--page-offset must be a non-negative integer');

Type guard

function isNonNegativeInt(v) {
  const n = Number(v);
  return Number.isFinite(n) && Number.isInteger(n) && n >= 0;
}

Try / catch

try {
  await run({ pageOffset: requireNonNegativeInt(rawOffset, 'page-offset') });
} catch (err) {
  if (err.name === 'ArgumentError' && /non-negative integer/.test(err.message)) {
    pageOffset = 0; // fall back to first page
  } else throw err;
}

Prevention

When it happens

Trigger: Calling a suno command with `--page-offset -1`, `--page-offset 1.5`, `--page-offset abc`, or an empty value that coerces to NaN. Any negative offset intended to mean 'last page' or 'auto' is unsupported.

Common situations: Trying negative offsets to page backwards; pasting fractional values; shell variable interpolating to an empty or non-numeric string (e.g. `--page-offset $PAGE` with PAGE unset).

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