jackwener/OpenCLI · error · InvalidArgumentError

${label} must be a positive integer. Received: "${String(raw

Error message

${label} must be a positive integer. Received: "${String(raw)}"

What it means

parsePositiveInt validates numeric CLI options such as --concurrency and --timeout in the auth commands. Any value that is not a whole number greater than zero (or empty/undefined, which falls back to the default) raises this commander InvalidArgumentError. The label in the message identifies which option was invalid.

Source

Thrown at src/commands/auth.ts:76

  now?: Date;
}

interface AuthRefreshSiteState {
  last_touched_at?: string;
  last_attempt_at?: string;
  last_status?: AuthRefreshStatus;
}

interface AuthRefreshState {
  version: number;
  sites: Record<string, AuthRefreshSiteState>;
}

function parsePositiveInt(raw: string | number | undefined, label: string, fallback: number): number {
  if (raw === undefined || raw === null || raw === '') return fallback;
  const parsed = Number(raw);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new InvalidArgumentError(`${label} must be a positive integer. Received: "${String(raw)}"`);
  }
  return parsed;
}

function parseSiteFilter(raw: string | undefined): Set<string> | null {
  if (!raw || !raw.trim()) return null;
  const sites = raw.split(',').map(site => site.trim()).filter(Boolean);
  return sites.length > 0 ? new Set(sites) : null;
}

function defaultAuthRefreshStatePath(): string {
  return join(homedir(), '.opencli', 'auth-refresh.json');
}

function emptyAuthRefreshState(): AuthRefreshState {
  return { version: AUTH_REFRESH_STATE_VERSION, sites: {} };
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a whole number >= 1, e.g. --concurrency 4 --timeout 20.
2. Omit the flag entirely to use the built-in default (3/8 for quick, 20 for full mode).
3. Fix the variable/interpolation in scripts that generate the command.

Example fix

// before
opencli auth status --concurrency 0
// after
opencli auth status --concurrency 4

function isPositiveInt(v: unknown): v is number {
  return Number.isInteger(v) && (v as number) > 0;
}
if (opts.concurrency !== undefined && !isPositiveInt(opts.concurrency)) {
  throw new Error('--concurrency must be a positive integer');
}

const isPositiveInt = (v: unknown): v is number =>
  typeof v === 'number' && Number.isInteger(v) && v > 0;

try {
  await opencli.authStatus({ concurrency: opts.concurrency });
} catch (e) {
  if (/must be a positive integer/.test(e.message)) {
    console.error(`Bad numeric option: ${e.message}. Omit the flag to use the default.`);
  } else throw e;
}

When it happens

Trigger: opencli auth status --concurrency 0, --concurrency -3, --concurrency 2.5, --concurrency abc, or --timeout '10 ' (non-numeric); also passing floats or strings that Number() cannot parse to an integer.

Common situations: Typos like --concurrency 1o; shell scripts interpolating empty or garbage values into the flag; assuming 0 means 'unlimited'; copy-pasting decimal defaults like 1.5.

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

• <train-no> "${trainNo}" does not look like a 12306 internal
• --from station must not be empty
• --to station must not be empty
• --seat-types must contain only 12306 seat letters/digits (A-
• --from and --to must differ; both resolved to ${fromStation.

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