abhigyanpatwari/GitNexus · error · Error

${flag} must be a positive integer

Error message

${flag} must be a positive integer

What it means

positiveInteger() validates that a CLI flag value for `gitnexus analyze --watch` is an integer >= 1 before it is used (e.g. worker pool size, timeout, max file size). It throws when Number(value) is NaN, a non-integral number, or less than 1. This guards the watch pipeline from nonsensical numeric configuration.

Source

Thrown at gitnexus/src/cli/analyze-watch.ts:90

  readonly maxFileSize: string | undefined;
  readonly workerTimeout: string | undefined;
  readonly verbose: string | undefined;
}

function setEnvironment(name: string, value: string | undefined): void {
  if (value === undefined) delete process.env[name];
  else process.env[name] = value;
}

function positiveInteger(
  value: string | undefined,
  flag: string,
  maximum?: number,
): number | undefined {
  if (value === undefined) return undefined;
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed < 1)
    throw new Error(`${flag} must be a positive integer`);
  if (maximum !== undefined && parsed > maximum) {
    throw new Error(`${flag} must not exceed ${maximum}`);
  }
  return parsed;
}

export async function resolveWatchOptions(
  repoPath: string,
  cli: WatchCliOptions,
  baseline: WatchEnvironmentBaseline,
  reportIgnoredConfig: (names: readonly string[]) => void = () => {},
): Promise<CoreAnalyzeOptions> {
  const config = (await loadAnalyzeConfigStrict(repoPath)) ?? {};
  const merged = mergeAnalyzeOptions(cli, config);
  const unsupported = [
    ['--force', cli.force],
    ['--no-parse-cache', cli.parseCache === false],
    ['--repair-fts', cli.repairFts],

View on GitHub (pinned to 0d1aed942f)

Solutions

1. Pass a whole number >= 1 for the flag (e.g. --worker-pool-size 4).
2. Remove unit suffixes and quotes: use --max-file-size 1048576, not 10mb.
3. Check the shell variable actually expands to a bare integer (echo it) before invoking the CLI.
4. If a maximum applies, stay at or below it (see the companion 'must not exceed' error).

Example fix

// before
gitnexus analyze --watch --worker-pool-size 0
// after
gitnexus analyze --watch --worker-pool-size 4

function isValidPositiveInt(v) {
  const n = Number(v);
  return v !== undefined && Number.isInteger(n) && n >= 1;
}
if (!isValidPositiveInt(process.argv.workerPoolSize)) throw new Error('workerPoolSize must be a positive integer');

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

When it happens

Trigger: Passing --worker-pool-size=0, --worker-timeout-seconds=2.5, --max-file-size=abc, or any flag routed through positiveInteger with a value that parses to NaN, a float, or an integer < 1.

Common situations: Typo in a numeric flag value, copy-pasting a float from documentation, shell variable expanding empty or to a unit-suffixed string like '10mb', or setting a value to 0 expecting 'unlimited'.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• ${flag} must not exceed ${maximum}
• ${flag} must be a positive integer
• Invalid URL
• Only https:// and http:// git URLs are allowed
• ${flag} must be a positive integer

AI-assisted analysis of abhigyanpatwari/GitNexus@0d1aed942f (2026-09-08). Data as JSON: /api/errors/c1173e8cfffbdc9e. Report an issue: GitHub.