abhigyanpatwari/GitNexus · error · Error

${flag} must not exceed ${maximum}

Error message

${flag} must not exceed ${maximum}

What it means

positiveInteger() also enforces an optional upper bound: when the caller passes a `maximum`, any parsed integer above it is rejected with '<flag> must not exceed <maximum>'. It exists to cap resource-consuming watch options (e.g. worker pool size) at safe limits.

Source

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

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

View on GitHub (pinned to 0d1aed942f)

Solutions

1. Lower the flag value to at most the stated maximum in the message.
2. Read `gitnexus analyze --watch --help` for the documented cap for each numeric option.
3. If you genuinely need a higher value, run the non-watch `analyze` path or file an issue to raise the cap.
4. Clamp the value in your wrapper script before invoking the CLI.

Example fix

// before
gitnexus analyze --watch --worker-pool-size 512
// after
gitnexus analyze --watch --worker-pool-size 8

const MAX_WORKER_POOL_SIZE = 64; // check --help for the actual cap
const n = Number(opts.workerPoolSize);
if (n > MAX_WORKER_POOL_SIZE) opts.workerPoolSize = MAX_WORKER_POOL_SIZE;

When it happens

Trigger: Calling a watch-related flag whose value parses to a valid positive integer but is greater than the caller-declared maximum (e.g. --worker-pool-size 1000 when the cap is lower).

Common situations: Inflating worker pool size on a small machine, guessing a timeout in the wrong unit (milliseconds vs seconds) producing an enormous number, or scripting a default that exceeds the cap.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• ${flag} must be a positive integer
• ${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/c1ed35c53d9f3e6b. Report an issue: GitHub.