{"record":{"id":"0a4b38d6e98a5c70","repo":"stablyai/orca","slug":"name-must-be-an-integer-from-1-through-maximu","errorCode":null,"errorMessage":"${name} must be an integer from 1 through ${maximum}","messagePattern":"(.+?) must be an integer from 1 through (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"config/scripts/remote-shared-control-retirement-probe.ts","lineNumber":247,"sourceCode":"          .sort((left, right) => right.memory - left.memory)\n          .slice(0, 5)\n          .map((session) => ({\n            pid: session.pid,\n            cpu: session.cpu,\n            memory: session.memory\n          }))\n      }))\n  }\n}\n\nfunction readProbeInteger(name: string, fallback: number, maximum: number): number {\n  const value = process.env[name]\n  if (value === undefined) {\n    return fallback\n  }\n  const parsed = Number(value)\n  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > maximum) {\n    throw new Error(`${name} must be an integer from 1 through ${maximum}`)\n  }\n  return parsed\n}\n\nfunction wait(delayMs: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, delayMs))\n}\n\nvoid main().catch((error: unknown) => {\n  console.error(error)\n  process.exitCode = 1\n})\n","sourceCodeStart":229,"sourceCodeEnd":260,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/config/scripts/remote-shared-control-retirement-probe.ts#L229-L260","documentation":"Thrown by readProbeInteger() in the retirement probe when one of the tuning env vars (ORCA_PROBE_CYCLES, ORCA_PROBE_CONCURRENCY, ORCA_PROBE_SETTLE_MS, ORCA_PROBE_CLEANUP_TIMEOUT_MS) is set but not a safe integer in [1, maximum]. Each has a fallback if unset, so this only fires when an explicit value is out of bounds.","triggerScenarios":"Setting a probe env var to 0, a negative number, a decimal, a value above its cap (e.g. ORCA_PROBE_CONCURRENCY=500 when max is 200), or a non-numeric string. Number.isSafeInteger rejects NaN, Infinity, and decimals.","commonSituations":"A developer ramps up concurrency past the documented ceiling, or sets CYCLES=0 to skip, not realizing the minimum is 1.","solutions":["Omit the env var to use its documented fallback (CYCLES=10, CONCURRENCY=25, SETTLE_MS=250, CLEANUP_TIMEOUT_MS=10000).","Set the value within its allowed range: CYCLES 1–100, CONCURRENCY 1–200, SETTLE_MS 1–5000, CLEANUP_TIMEOUT_MS 1–30000."],"exampleFix":"// before\nORCA_PROBE_CONCURRENCY=500 ORCA_PROBE_ENVIRONMENT_NAME=env1 node --import tsx .../remote-shared-control-retirement-probe.ts\n// after\nORCA_PROBE_CONCURRENCY=200 ORCA_PROBE_ENVIRONMENT_NAME=env1 node --import tsx .../remote-shared-control-retirement-probe.ts","handlingStrategy":"validation","validationCode":"function readBoundedInt(name, fallback, maximum) {\n  const value = process.env[name]\n  if (value === undefined) return fallback\n  const parsed = Number(value)\n  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > maximum) {\n    throw new Error(`${name} must be an integer from 1 through ${maximum}`)\n  }\n  return parsed\n}","typeGuard":"function isBoundedSafeInt(value, max) {\n  return Number.isSafeInteger(value) && value >= 1 && value <= max\n}","tryCatchPattern":null,"preventionTips":["Print the allowed range [1, maximum] in the error so the user knows the bounds immediately.","Provide the fallback value in the env-var documentation so users know they can omit it."],"tags":["env-var","validation","range-check","probe"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}