{"record":{"id":"63dd6f9c08a858ed","repo":"abhigyanpatwari/GitNexus","slug":"flag-must-not-exceed-maximum","errorCode":null,"errorMessage":"${flag} must not exceed ${maximum}","messagePattern":"(.+?) must not exceed (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/cli/watch.ts","lineNumber":91,"sourceCode":"  readonly verbose: string | undefined;\n}\n\nfunction setEnvironment(name: string, value: string | undefined): void {\n  if (value === undefined) delete process.env[name];\n  else process.env[name] = value;\n}\n\nfunction positiveInteger(\n  value: string | undefined,\n  flag: string,\n  maximum?: number,\n): number | undefined {\n  if (value === undefined) return undefined;\n  const parsed = Number(value);\n  if (!Number.isInteger(parsed) || parsed < 1)\n    throw new Error(`${flag} must be a positive integer`);\n  if (maximum !== undefined && parsed > maximum) {\n    throw new Error(`${flag} must not exceed ${maximum}`);\n  }\n  return parsed;\n}\n\nexport async function resolveWatchOptions(\n  repoPath: string,\n  cli: WatchCliOptions,\n  baseline: WatchEnvironmentBaseline,\n  reportIgnoredConfig: (names: readonly string[]) => void = () => {},\n): Promise<CoreAnalyzeOptions> {\n  const config = (await loadAnalyzeConfigStrict(repoPath)) ?? {};\n  const merged = mergeAnalyzeOptions(cli, config);\n  const unsupported = [\n    ['--force', cli.force],\n    ['--repair-fts', cli.repairFts],\n    ['--embeddings', cli.embeddings],\n    ['--drop-embeddings', cli.dropEmbeddings],\n    ['--skills', cli.skills],","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/52924ef12c2290ceee4612526a828ec4cdf2047f/gitnexus/src/cli/watch.ts#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Lower the flag value to at or below the documented maximum stated in the error message (`${flag} must not exceed ${maximum}`).","Check the current flag's cap with `gitnexus analyze --help` and adjust your script's constants.","Fix unit conversions (verify bytes vs MB) so the final value stays within the bound.","Clamp the value programmatically in wrappers: `Math.min(value, MAX_ALLOWED)`."],"exampleFix":"// before\ngitnexus analyze --watch --worker-pool-size 64   // exceeds cap\n\n// after\ngitnexus analyze --watch --worker-pool-size 16","handlingStrategy":"validation","validationCode":"function assertWithinMax(value: number | undefined, flag: string, maximum: number): void {\n  if (value !== undefined && value > maximum) {\n    throw new Error(`${flag} must not exceed ${maximum}, got ${value}`);\n  }\n}\nassertWithinMax(parsedWorkers, '--worker-pool-size', 32);","typeGuard":"function isWithin(v: number, max: number): boolean {\n  return Number.isInteger(v) && v >= 1 && v <= max;\n}","tryCatchPattern":"try {\n  await runWatchCommand(argv);\n} catch (e) {\n  const m = e.message.match(/^(\\S+) must not exceed (\\d+)$/);\n  if (m) {\n    console.error(`Clamp ${m[1]} to <= ${m[2]} and retry.`);\n    process.exitCode = 2;\n  } else throw e;\n}","preventionTips":["Check `gitnexus analyze --help` for each flag's documented maximum before scripting values.","Clamp programmatically (Math.min) when computing values from host resources.","Re-verify unit conversions (bytes vs MB) whenever you change a size flag."],"tags":["cli","argument-validation","bounds-check","watch-mode"],"backgroundTag":"invalid-cli-argument","analyzedSha":"52924ef12c2290ceee4612526a828ec4cdf2047f","analyzedAt":"2026-09-01T13:15:02.810Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}