{"record":{"id":"3f2a43c969502d39","repo":"JuliusBrussee/caveman","slug":"timeoutms-must-be-a-positive-integer","errorCode":null,"errorMessage":"timeoutMs must be a positive integer","messagePattern":"timeoutMs must be a positive integer","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/sdk/typescript/src/index.ts","lineNumber":356,"sourceCode":"  try {\n    parsed = new URL(value);\n  } catch {\n    throw new Error(`${name} must be an absolute http(s) URL`);\n  }\n  if ((parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") || !parsed.hostname || parsed.username || parsed.password) {\n    throw new Error(`${name} must be an absolute http(s) URL without credentials`);\n  }\n  if (parsed.search || parsed.hash) throw new Error(`${name} must not contain a query or fragment`);\n  return value.replace(/\\/+$/, \"\");\n}\n\nexport class Cave {\n  readonly options: CaveOptions;\n\n  constructor(options: CaveOptions) {\n    if (!options.apiKey || !options.baseURL || !options.agent) throw new Error(\"apiKey, baseURL, and agent are required\");\n    if (options.timeoutMs !== undefined && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0)) {\n      throw new Error(\"timeoutMs must be a positive integer\");\n    }\n    // CAVE_WORKFLOW lets a wrapper (`cave wrap --workflow x`) label every request\n    // from an SDK app without a code change. An explicit option always wins.\n    // globalThis lookup keeps the SDK browser-neutral (no node type dependency).\n    // The env value is normalized to the gateway's label rule (lowercase\n    // [a-z0-9_-], max 96) — an invalid ambient value is ignored rather than\n    // 400-ing every request. Mirrors caveman_cloud (Python).\n    const envRaw = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.[\"CAVE_WORKFLOW\"]?.toLowerCase();\n    const envWorkflow = envRaw && /^[a-z0-9_-]{1,96}$/.test(envRaw) ? envRaw : undefined;\n    const normalized: CaveOptions = {\n      ...options,\n      baseURL: normalizedServiceURL(options.baseURL, \"baseURL\"),\n      ...(options.controlURL === undefined\n        ? {}\n        : { controlURL: normalizedServiceURL(options.controlURL, \"controlURL\") }),\n    };\n    this.options = !normalized.defaultWorkflow && envWorkflow\n      ? { ...normalized, defaultWorkflow: envWorkflow }","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/sdk/typescript/src/index.ts#L338-L374","documentation":"The Cave constructor validates the optional timeoutMs option: if provided, it must be a safe integer strictly greater than zero. Zero, negative numbers, NaN, Infinity, and non-integers (floats, strings, big values beyond Number.MAX_SAFE_INTEGER) are rejected so timeout handling downstream can rely on a valid millisecond value.","triggerScenarios":"new Cave({ ..., timeoutMs: 0 }) (e.g. \"disable timeout\" attempt), timeoutMs: -1, timeoutMs: 1.5, timeoutMs: Number(env) producing NaN, or timeoutMs: \"30000\" (string).","commonSituations":"Using 0 intending 'no timeout'; reading the value from env/config where it stays a string or empty; seconds-vs-milliseconds confusion producing a fractional or wrong-scale value; JSON config containing null.","solutions":["Pass a positive integer of milliseconds, e.g. timeoutMs: 30000.","To use no timeout, omit the option entirely (undefined is allowed) instead of passing 0.","Coerce env/config values explicitly: `const t = Number(raw); if (Number.isSafeInteger(t) && t > 0) ...`."],"exampleFix":"// before\nnew Cave({ apiKey, baseURL, agent: \"x\", timeoutMs: Number(process.env.TIMEOUT) });\n\n// after\nconst t = Number(process.env.TIMEOUT);\nnew Cave({ apiKey, baseURL, agent: \"x\", ...(Number.isSafeInteger(t) && t > 0 ? { timeoutMs: t } : {}) });","handlingStrategy":"validation","validationCode":"function parseTimeoutMs(raw: string | undefined): number | undefined {\n  if (raw === undefined || raw === \"\") return undefined;\n  const n = Number(raw);\n  if (!Number.isSafeInteger(n) || n <= 0) throw new Error(`timeoutMs must be a positive integer, got ${raw}`);\n  return n;\n}","typeGuard":"const isValidTimeoutMs = (v: unknown): v is number => typeof v === \"number\" && Number.isSafeInteger(v) && v > 0;","tryCatchPattern":"try {\n  const cave = new Cave(options);\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"timeoutMs\")) {\n    // drop the bad option and retry with the SDK default\n    const { timeoutMs, ...rest } = options;\n    const cave = new Cave(rest);\n  } else throw e;\n}","preventionTips":["Omit timeoutMs entirely for default behavior; never use 0 to mean 'no timeout'.","Coerce and validate env/config numbers with Number() plus Number.isSafeInteger checks.","Keep the value in milliseconds consistently; document the unit where it's configured."],"tags":["validation","constructor","timeout","configuration"],"backgroundTag":"invalid-argument-value","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}