JuliusBrussee/caveman · error · Error

caveman agent: artifact maxInlineTokens must be a…

Error message

caveman agent: artifact maxInlineTokens must be a non-negative integer

What it means

artifact() defaults maxInlineTokens to 1200 but validates any explicitly provided value must be a non-negative safe integer. It throws when maxInlineTokens is negative, fractional, NaN, Infinity, or otherwise not a Number.isSafeInteger. The value controls how many tokens of the artifact may be inlined, so only 0 and positive integers are meaningful.

Solutions

Pass a non-negative safe integer (>= 0), or omit maxInlineTokens to use the default 1200.
Clamp the computed value: Math.max(0, Math.floor(value)).
Validate before the call: Number.isSafeInteger(v) && v >= 0.

Example fix

// before
const art = artifact({ id: "report", maxInlineTokens: -100 });
// after
const art = artifact({ id: "report", maxInlineTokens: Math.max(0, computedTokens) });

Defensive patterns

Strategy: validation

Validate before calling

function validMaxInlineTokens(v) { return v === undefined || (Number.isSafeInteger(v) && v >= 0); }
if (!validMaxInlineTokens(opts.maxInlineTokens)) throw new Error(`maxInlineTokens must be a non-negative integer, got ${opts.maxInlineTokens}`);

Type guard

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

Try / catch

let art;
try { art = artifact({ id, maxInlineTokens }); }
catch (e) { if (String(e.message).includes("maxInlineTokens")) art = artifact({ id }); else throw e; }

Prevention

Clamp computed budgets: Math.max(0, Math.floor(value)).
Don't pass token math results directly; round to integers first.
Rely on the default 1200 unless you have a concrete budget reason.

When it happens

Trigger: Calling artifact({ maxInlineTokens: -5 }) or any negative number; a float such as 100.5; NaN or Infinity; a non-number coerced incorrectly. The default (omitted) value of 1200 never triggers it.

Common situations: Subtracting tokens from a budget and going below zero; passing a computed average or ratio that is fractional; passing a string or null from parsed config.

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/b6b01703c1fb2be8. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/primitives.ts:383

  };
  return Object.freeze(definition);
}

export interface ArtifactDefinition {
  readonly kind: "artifact";
  readonly strategy: "verbatim" | "json-index" | "page";
  readonly maxInlineTokens: number;
  readonly recovery: "exact_ccr" | "source_ref";
}

export function artifact(options: {
  strategy?: ArtifactDefinition["strategy"];
  maxInlineTokens?: number;
  recovery?: ArtifactDefinition["recovery"];
} = {}): ArtifactDefinition {
  const maxInlineTokens = options.maxInlineTokens ?? 1_200;
  if (!Number.isSafeInteger(maxInlineTokens) || maxInlineTokens < 0) {
    throw new Error("caveman agent: artifact maxInlineTokens must be a non-negative integer");
  }
  return Object.freeze({
    kind: "artifact",
    strategy: options.strategy ?? "page",
    maxInlineTokens,
    recovery: options.recovery ?? "exact_ccr",
  });
}

export interface OutputDefinition<TSchemaValue extends TSchema | undefined = TSchema | undefined> {
  readonly kind: "output";
  readonly maxTokens: number;
  readonly schema?: TSchemaValue;
}

export function output<T extends TSchema | undefined = undefined>(options: {
  maxTokens: number;
  schema?: T;

View on GitHub (pinned to 3ee70a1026)