JuliusBrussee/caveman · error

caveman agent: subagent maxContextTokens must be a positive…

Error message

caveman agent: subagent maxContextTokens must be a positive integer

What it means

`subagent()` validates `maxContextTokens`, which defaults to 128,000 and bounds the subagent's context window usage. It must be a positive safe integer (this option, unlike maxTokens, has no undefined escape — the resolved default is always checked). The library throws at tool-creation time for 0, negatives, floats, NaN, or values above Number.MAX_SAFE_INTEGER.

Solutions

1. Pass a positive integer, e.g. `subagent({ maxContextTokens: 200_000 })`, or omit it to use the 128,000 default.
2. Coerce and validate config: `const v = Number.parseInt(raw, 10)`; check `Number.isSafeInteger(v) && v > 0`.
3. Match the value to your model provider's actual context window to avoid later runtime limits.

Example fix

// before
subagent({ name: "reader", maxContextTokens: "200,000" })
// after
subagent({ name: "reader", maxContextTokens: 200_000 })

const assertContextTokens = (v) => {
  const n = typeof v === "string" ? Number.parseInt(v.replaceAll(",", ""), 10) : v;
  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`maxContextTokens must be a positive integer, got ${v}`);
  return n;
};
subagent({ name: "reader", maxContextTokens: assertContextTokens(cfg.maxContextTokens) });

const isPosInt = (v) => typeof v === "number" && Number.isSafeInteger(v) && v > 0;

try {
  const t = subagent({ maxContextTokens: cfg.maxContextTokens });
} catch (e) {
  if (e.message.includes("maxContextTokens must be a positive integer")) {
    console.error(`Bad maxContextTokens: ${JSON.stringify(cfg.maxContextTokens)}; using default 128000`);
    return subagent({ name: "reader" }); // falls back to library default
  }
  throw e;
}

When it happens

Trigger: Calling `subagent({ maxContextTokens: 0 })`, `subagent({ maxContextTokens: -1 })`, `subagent({ maxContextTokens: 128000.5 })`, `subagent({ maxContextTokens: NaN })`, or passing a numeric string from config.

Common situations: Reading the value from a JSON/ENV config as a string; unit confusion between tokens and characters producing fractions; copying a model context size with a comma ('128,000') that fails numeric parsing.

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

• caveman agent: subagent maxCalls must be a positive integer
• caveman agent: subagent maxCostUsd must be positive
• caveman agent: subagent maxTokens must be a positive integer
• apiKey, baseURL, and agent are required
• ASGI context resolver or request bounds are invalid

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

Appendix: source

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

  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 }),
      maxContextTokens,
    },
    async execute() {

View on GitHub (pinned to 3ee70a1026)