JuliusBrussee/caveman · error · Error

caveman agent: subagent maxInputChars must be a positive int

Error message

caveman agent: subagent maxInputChars must be a positive integer

What it means

Thrown by the subagent() builder (packages/agent/src/index.ts:169): options.maxInputChars is not a positive safe integer. It defaults to 32768; an explicit value must be a whole number >= 1 (and within Number.MAX_SAFE_INTEGER) because it caps subagent input deterministically.

Source

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

  maxInputChars?: number;
  maxCalls?: number;
  /**
   * This child's wallet in USD. Under a USD-metered run the wallet is carved
   * out of the parent's **remaining** budget when the child is spawned, and its
   * unspent remainder returns to the parent when the child finishes.
   */
  maxCostUsd?: number;
  /**
   * This child's wallet in tokens — the denomination sibling of `maxCostUsd`,
   * used by a token-metered run. A token-metered run cannot fund a subagent
   * that declares no token wallet.
   */
  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({

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Pass a positive integer literal or validated integer, e.g. 65536.
2. When reading from env/config, coerce and validate first: Number.isSafeInteger(n) && n > 0.
3. For 'unlimited' intent, omit the option and use the default (32768) or pick an explicit large integer cap.

Example fix

// before
subagent({ maxInputChars: Number(process.env.SUBAGENT_INPUT), /* ... */ }); // string or NaN

// after
const maxInputChars = Number(process.env.SUBAGENT_INPUT);
subagent({ maxInputChars: Number.isSafeInteger(maxInputChars) && maxInputChars > 0 ? maxInputChars : 32768, /* ... */ });

function isPositiveSafeInteger(v: unknown): v is number {
  return typeof v === "number" && Number.isSafeInteger(v) && v > 0;
}
const maxInputChars = isPositiveSafeInteger(config.maxInputChars) ? config.maxInputChars : undefined; // falls back to 32768 default

function isPositiveSafeInteger(v: unknown): v is number {
  return typeof v === "number" && Number.isSafeInteger(v) && v > 0;
}

When it happens

Trigger: Calling subagent({ maxInputChars, ... }) with 0, a negative number, a fractional value like 1024.5, NaN/Infinity, or a non-number (e.g. the string '32768').

Common situations: Passing a computed size that can be 0 (e.g. derived from remaining context); loading the value from config/env without coercion (string from process.env); using Infinity intending 'no limit'; float math producing fractional caps.

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
• caveman agent: subagent maxContextTokens must be a positive
• option not found

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/c38ca2a3640da1d0. Report an issue: GitHub.