abhigyanpatwari/GitNexus · error

${flag} must be a positive integer

Error message

${flag} must be a positive integer

What it means

Thrown by the positiveInteger flag parser in watch.ts when a numeric CLI flag for `analyze --watch` (worker pool size, worker timeout seconds, max file size, etc.) is not an integer >= 1. The value is coerced with Number(), so non-numeric strings, decimals, zero, and negative numbers all fail.

Source

Thrown at gitnexus/src/cli/watch.ts:89

  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],
    ['--repair-fts', cli.repairFts],
    ['--embeddings', cli.embeddings],

View on GitHub (pinned to 52924ef12c)

Solutions

1. Pass a whole number >= 1 for the flag, e.g. `--worker-pool-size 4`, `--max-file-size 5242880`.
2. Strip units and convert to the expected unit (bytes for max-file-size, seconds for timeout) before invoking the CLI.
3. Fix the shell script so empty variables are defaulted: `SIZE=${SIZE:-4}`.
4. Validate inputs in your wrapper (integer check) before exec'ing the gitnexus CLI.

Example fix

// before
gitnexus analyze --watch --worker-timeout-seconds 1.5

// after
gitnexus analyze --watch --worker-timeout-seconds 2

function assertPositiveInt(value: string | number | undefined, flag: string): number | undefined {
  if (value === undefined) return undefined;
  const n = Number(value);
  if (!Number.isInteger(n) || n < 1) throw new Error(`${flag} must be a positive integer, got ${value}`);
  return n;
}
// call before spawning: assertPositiveInt(process.env.WORKERS, '--worker-pool-size')

function isPositiveInt(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v >= 1;
}

try {
  await runWatchCommand(argv);
} catch (e) {
  if (/(must be a positive integer|must not exceed)/.test(e.message)) {
    console.error(`Bad flag value: ${e.message} — see gitnexus analyze --help`);
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Passing e.g. `--worker-pool-size 0`, `--worker-timeout-seconds 2.5`, `--max-file-size abc`, `--max-file-size -1`, or an empty value to analyze --watch; also when a wrapper script forwards a blank/unset variable as the flag value.

Common situations: Typos in shell scripts (`SIZE=${SIZE}` with SIZE empty), pasting values with units ('10mb' instead of byte counts), using fractional seconds, or confusing 0-based with 1-based minimums.

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}
• analyze --watch does not support ${unsupported.map(([name])
• Watch refresh is already running
• analyze --watch does not support ${unsupported.map(([name])
• Ignore controls remain invalid; fix them before indexing mor

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-09-01). Data as JSON: /api/errors/7447d230c5fd3f17. Report an issue: GitHub.