caveman agent: subagent maxTokens must be a positive integer

Error message

caveman agent: subagent maxTokens must be a positive integer

What it means

`subagent()` accepts an optional `maxTokens` option limiting per-call model output. When provided, it must be a positive safe integer; undefined skips the check (no limit). The library throws at tool-creation time when a caller passes 0, a negative number, a float, or a non-integer.

Solutions

Pass a positive integer, e.g. `subagent({ maxTokens: 4096 })`, or omit the option entirely for no limit.
Coerce string config with `Number.parseInt(raw, 10)` and check `Number.isSafeInteger(v) && v > 0` before passing.
To remove a cap, delete the maxTokens key rather than setting it to 0.

Example fix

// before
subagent({ name: "writer", maxTokens: cfg.maxTokens ?? 0 })
// after
const maxTokens = cfg.maxTokens === undefined ? undefined : Number.parseInt(cfg.maxTokens, 10);
subagent({ name: "writer", ...(maxTokens === undefined ? {} : { maxTokens }) })

Defensive patterns

Strategy: validation

Validate before calling

function normalizeMaxTokens(v) {
  if (v === undefined) return undefined;
  const n = typeof v === "string" ? Number.parseInt(v, 10) : v;
  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`maxTokens must be a positive integer, got ${v}`);
  return n;
}
const opts = { name: "writer" };
const mt = normalizeMaxTokens(cfg.maxTokens);
if (mt !== undefined) opts.maxTokens = mt;
subagent(opts);

Type guard

const isOptionalPosInt = (v) => v === undefined || (typeof v === "number" && Number.isSafeInteger(v) && v > 0);

Try / catch

try {
  const t = subagent({ maxTokens: cfg.maxTokens });
} catch (e) {
  if (e.message.includes("maxTokens must be a positive integer")) {
    console.warn("Ignoring invalid maxTokens; running without token cap");
    return subagent({}); // omit the option entirely
  }
  throw e;
}

Prevention

Remember maxTokens is optional — omit it rather than passing 0
Coerce numeric strings from config before passing
Type the option as number | undefined in your config layer so TS catches strings
Test tool construction with both present and absent optional options

When it happens

Trigger: Calling `subagent({ maxTokens: 0 })`, `subagent({ maxTokens: -100 })`, `subagent({ maxTokens: 1024.5 })`, `subagent({ maxTokens: NaN })`, or passing a string like `"4096"` from config.

Common situations: Copying provider maxOutputTokens as a string; computing the value from arithmetic that yields a float; attempting to disable the token cap by setting 0 instead of leaving it undefined.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/34ad719f94032c51. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/index.ts:182

  maxTokens?: number;
  maxContextTokens?: number;
}): ToolDefinition {
  const maxInputChars = options.maxInputChars ?? 32_768;
  if (!Number.isSafeInteger(maxInputChars) || maxInputChars <= 0) {
    throw new Error("caveman agent: subagent maxInputChars must be a positive integer");
  }
  const maxCalls = options.maxCalls ?? 1;
  const maxCostUsd = options.maxCostUsd ?? 1;
  const maxContextTokens = options.maxContextTokens ?? 128_000;
  if (!Number.isSafeInteger(maxCalls) || maxCalls <= 0) {
    throw new Error("caveman agent: subagent maxCalls must be a positive integer");
  }
  if (!Number.isFinite(maxCostUsd) || maxCostUsd <= 0) {
    throw new Error("caveman agent: subagent maxCostUsd must be positive");
  }
  if (options.maxTokens !== undefined &&
      (!Number.isSafeInteger(options.maxTokens) || options.maxTokens <= 0)) {
    throw new Error("caveman agent: subagent maxTokens must be a positive integer");
  }
  if (!Number.isSafeInteger(maxContextTokens) || maxContextTokens <= 0) {
    throw new Error("caveman agent: subagent maxContextTokens must be a positive integer");
  }
  return tool({
    name: options.name,
    description: options.description,
    input: schema.object({ task: schema.string() }),
    effect: "read",
    result: "auto",
    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
    runtime: {
      kind: "subagent",
      definition: options.agent,
      maxInputChars,
      maxCalls,
      maxCostUsd,
      ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),

View on GitHub (pinned to 3ee70a1026)