JuliusBrussee/caveman · error

page_size must be an integer from 1 to 500

Error message

page_size must be an integer from 1 to 500

What it means

Validation error from validateTraceSearch in the agent MCP server: page_size is outside the accepted range — it must be an integer between 1 and 500. Enforced so trace listing requests stay bounded for the API call behind the tool.

Solutions

1. Clamp page_size into [1, 500]: Math.min(500, Math.max(1, n)).
2. Round to an integer (Math.floor/round) before sending.
3. Coerce string values with Number()/parseInt and validate isSafeInteger.
4. Omit page_size to use the server default.

Example fix

// before
{ "page_size": 1000 }
// after
{ "page_size": 500 }

if (args.page_size !== undefined) {
  const n = Number(args.page_size);
  if (!Number.isSafeInteger(n) || n < 1 || n > 500)
    throw new Error("page_size must be an integer 1-500");
  args.page_size = n;
}

function isValidPageSize(v) {
  return v === undefined || (Number.isSafeInteger(v) && v >= 1 && v <= 500);
}

try {
  await traceSearch(args);
} catch (e) {
  if (e.message.startsWith("page_size must be")) {
    args.page_size = Math.min(500, Math.max(1, Math.round(Number(args.page_size) || 1)));
    return traceSearch(args);
  }
  throw e;
}

When it happens

Trigger: trace_search with {"page_size":0}, {"page_size":501}, {"page_size":10.5}, {"page_size":"25"} (string), or page_size from a config parsed as a string.

Common situations: CLI flags passed as strings and not converted; frontend sliders allowing 0 or huge values; pagination copied from APIs with 1000-item limits; NaN/Infinity from bad arithmetic (fails Number.isSafeInteger).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• cursor has unknown key(s)
• cursor must be an object
• cave_budget_initial_invalid
• cursor.sort_value is required
• must be base64 or null

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

Appendix: source

Thrown at packages/cli/src/agent-mcp.ts:517

function optionalEnum(args: JSONObject, key: string, values: string[]): void {
  const value = args[key];
  if (value !== undefined && (typeof value !== "string" || !values.includes(value))) {
    throw new Error(`${key} must be one of ${values.join(", ")}`);
  }
}

function validateTraceSearch(args: JSONObject): void {
  validateTraceFilters(args);
  for (const key of ["from", "to"]) {
    const value = args[key];
    if (value !== undefined && typeof value !== "string") throw new Error(`${key} must be a string`);
  }
  optionalEnum(args, "date_field", ["occurred", "updated"]);
  optionalEnum(args, "group_by", ["session", "workflow", "model", "member"]);
  const pageSize = args.page_size;
  if (pageSize !== undefined && (!Number.isSafeInteger(pageSize) || (pageSize as number) < 1 || (pageSize as number) > 500)) {
    throw new Error("page_size must be an integer from 1 to 500");
  }
  const sort = args.sort;
  if (sort !== undefined) {
    if (!sort || typeof sort !== "object" || Array.isArray(sort)) throw new Error("sort must be an object");
    const unknown = Object.keys(sort).filter((key) => key !== "by" && key !== "dir");
    if (unknown.length > 0) throw new Error(`sort has unknown key(s): ${unknown.sort().join(", ")}`);
    optionalEnum(sort, "by", ["timestamp", "total_cost_usd", "latency_ms", "total_tokens"]);
    optionalEnum(sort, "dir", ["asc", "desc"]);
  }
  const cursor = args.cursor;
  if (cursor !== undefined) {
    if (!cursor || typeof cursor !== "object" || Array.isArray(cursor)) throw new Error("cursor must be an object");
    const unknown = Object.keys(cursor).filter((key) => key !== "sort_value" && key !== "request_id" && key !== "group_key");
    if (unknown.length > 0) throw new Error(`cursor has unknown key(s): ${unknown.sort().join(", ")}`);
    if (typeof cursor.sort_value !== "string" || cursor.sort_value === "") throw new Error("cursor.sort_value is required");
    for (const key of ["request_id", "group_key"]) {
      if (cursor[key] !== undefined && typeof cursor[key] !== "string") throw new Error(`cursor.${key} must be a string`);
    }

View on GitHub (pinned to 3ee70a1026)