abhigyanpatwari/GitNexus · error

${flag} must not exceed ${maximum}

Error message

${flag} must not exceed ${maximum}

What it means

Thrown by positiveInteger in watch.ts when a numeric watch flag parses fine but exceeds the optional `maximum` bound configured for that flag. Each bounded flag (e.g. worker pool size caps, max file size caps) rejects values above its documented ceiling.

Source

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

  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],
    ['--drop-embeddings', cli.dropEmbeddings],
    ['--skills', cli.skills],

View on GitHub (pinned to 52924ef12c)

Solutions

  1. Lower the flag value to at or below the documented maximum stated in the error message (`${flag} must not exceed ${maximum}`).
  2. Check the current flag's cap with `gitnexus analyze --help` and adjust your script's constants.
  3. Fix unit conversions (verify bytes vs MB) so the final value stays within the bound.
  4. Clamp the value programmatically in wrappers: `Math.min(value, MAX_ALLOWED)`.

Example fix

// before
gitnexus analyze --watch --worker-pool-size 64   // exceeds cap

// after
gitnexus analyze --watch --worker-pool-size 16
Defensive patterns

Strategy: validation

Validate before calling

function assertWithinMax(value: number | undefined, flag: string, maximum: number): void {
  if (value !== undefined && value > maximum) {
    throw new Error(`${flag} must not exceed ${maximum}, got ${value}`);
  }
}
assertWithinMax(parsedWorkers, '--worker-pool-size', 32);

Type guard

function isWithin(v: number, max: number): boolean {
  return Number.isInteger(v) && v >= 1 && v <= max;
}

Try / catch

try {
  await runWatchCommand(argv);
} catch (e) {
  const m = e.message.match(/^(\S+) must not exceed (\d+)$/);
  if (m) {
    console.error(`Clamp ${m[1]} to <= ${m[2]} and retry.`);
    process.exitCode = 2;
  } else throw e;
}

Prevention

When it happens

Trigger: Passing `--worker-pool-size 999` (above its cap), an oversized `--max-file-size`, or a timeout seconds value beyond its maximum; also when scripts multiply values (e.g. MB-to-bytes conversion) overshooting the bound.

Common situations: Machine-specific caps exceeded on small hosts, copy-pasted tuning values from another project's docs, unit conversion mistakes (MB vs bytes) producing huge numbers.

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

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