{"record":{"id":"e5205ab37e2452e0","repo":"JuliusBrussee/caveman","slug":"cave-run-deadline-invalid","errorCode":"cave_run_deadline_invalid","errorMessage":"cave_run_deadline_invalid","messagePattern":"cave_run_deadline_invalid","errorType":"error_code","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/agent/src/runtime.ts","lineNumber":1085,"sourceCode":"    throw new Error(\"cave_subagent_concurrency_limit_invalid\");\n  }\n  if (options.lockedBuild !== undefined && options.candidatePlan !== undefined) {\n    throw new Error(\"cave_execution_authorization_ambiguous\");\n  }\n  // Budget shape is settled before anything else happens: an ambiguous or\n  // unbounded budget must fail at run() start, not after the first dollar.\n  // maxCostUsd and budget are two different contracts for the same money —\n  // one terminates with an error, the other returns a planned partial result —\n  // so carrying both would leave the run's own stop semantics undecided.\n  if (options.budget !== undefined && options.maxCostUsd !== undefined) {\n    throw new Error(\"cave_budget_conflicting_cap\");\n  }\n  const budgetMeter = executionContext.budgetMeter ?? (options.budget === undefined\n    ? undefined\n    : new BudgetMeter(normalizeRunBudget(options.budget)));\n  if (options.deadlineMs !== undefined &&\n      (!Number.isSafeInteger(options.deadlineMs) || options.deadlineMs <= 0)) {\n    throw new Error(\"cave_run_deadline_invalid\");\n  }\n  if (options.maxSubagentDepth !== undefined &&\n      (!Number.isSafeInteger(options.maxSubagentDepth) || options.maxSubagentDepth <= 0 ||\n        options.maxSubagentDepth > ABSOLUTE_SUBAGENT_DEPTH_LIMIT)) {\n    throw new Error(\"cave_subagent_depth_limit_invalid\");\n  }\n  const deadlineAt = executionContext.deadlineAt ?? (options.deadlineMs === undefined\n    ? undefined\n    : performance.now() + options.deadlineMs);\n  // A controller with nothing to release would be a silent no-op at the\n  // checkpoint that expected it to matter.\n  if (options.budgetController !== undefined && budgetMeter === undefined) {\n    throw new Error(\"cave_budget_controller_without_budget\");\n  }\n  const breakers = options.breakers === undefined\n    ? undefined\n    : new BreakerState(normalizeRunBreakers(options.breakers, budgetMeter !== undefined));\n  const efficiencyPlan = options.lockedBuild?.selected_plan ?? options.candidatePlan;","sourceCodeStart":1067,"sourceCodeEnd":1103,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/runtime.ts#L1067-L1103","documentation":"RunOptions.deadlineMs sets a wall-clock deadline for the run, stopping at the same between-call points as budget exhaustion. streamAgentInternal validates it: it must be a safe integer greater than 0. Zero, negative, fractional, or non-finite values throw before any execution.","triggerScenarios":"Passing deadlineMs: 0 (to mean \"no deadline\"), a negative duration, a fractional ms value, NaN/Infinity, or a numeric string from env/CLI config.","commonSituations":"Using 0 as a sentinel for \"unlimited\" (the correct way is to omit the option); computing the deadline from Date subtraction producing a float or negative remainder; reading ms durations from config as strings.","solutions":["Pass a positive safe integer of milliseconds, e.g. deadlineMs: 60000.","Omit deadlineMs entirely when no deadline is wanted — do not use 0.","Sanitize derived values: Math.floor(remainingMs) and clamp to >= 1 before passing."],"exampleFix":"// before\nrunAgent(def, input, { deadlineMs: process.env.DEADLINE_MS as unknown as number });\n// after\nconst ms = Number.parseInt(process.env.DEADLINE_MS ?? \"\", 10);\nrunAgent(def, input, Number.isSafeInteger(ms) && ms > 0 ? { deadlineMs: ms } : {});","handlingStrategy":"validation","validationCode":"function isValidDeadlineMs(v) {\n  return v === undefined || (Number.isSafeInteger(v) && v > 0);\n}","typeGuard":"function hasValidDeadline(o) {\n  return o.deadlineMs === undefined ||\n    (Number.isSafeInteger(o.deadlineMs) && o.deadlineMs > 0);\n}","tryCatchPattern":"try {\n  await runAgent(def, input, opts);\n} catch (err) {\n  if (err.message === \"cave_run_deadline_invalid\") {\n    await runAgent(def, input, { ...opts, deadlineMs: undefined }); // run without deadline\n  } else throw err;\n}","preventionTips":["Omit deadlineMs rather than passing 0 for \"no deadline\".","Use Math.floor on derived remaining-time values.","Coerce env/config strings with parseInt and validate before use."],"tags":["agent-runtime","validation","timeout"],"backgroundTag":"invalid-duration-format","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"}