JuliusBrussee/caveman · error

filter status_class values must be 2xx, 4xx, or 5xx

Error message

filter status_class values must be 2xx, 4xx, or 5xx

What it means

The status_class filter accepts only the values "2xx", "4xx", or "5xx". Even if the value is a valid non-empty string array, any other element causes this error. It enforces an enum within the already-validated string-list shape.

Solutions

1. Use only '2xx', '4xx', or '5xx' as entries
2. Convert numeric status codes to their class (e.g. 200 -> '2xx') before calling
3. Split unsupported classes (3xx, 1xx) out — use a different filter or omit them

Example fix

// before
searchTraces({ filters: { status_class: ['200', '404'] } });
// after
searchTraces({ filters: { status_class: ['2xx', '4xx'] } });

function toStatusClass(code) {
  const c = Math.floor(Number(code) / 100);
  return [2, 4, 5].includes(c) ? `${c}xx` : null;
}
function assertStatusClass(list) {
  if (list !== undefined && list.some((e) => !['2xx', '4xx', '5xx'].includes(e))) {
    throw new Error("status_class values must be 2xx, 4xx, or 5xx");
  }
}

function isStatusClassArray(v) {
  return Array.isArray(v) && v.every((e) => ['2xx', '4xx', '5xx'].includes(e));
}

try {
  await searchTraces({ filters });
} catch (error) {
  if (error.message.startsWith('filter status_class values')) {
    filters.status_class = filters.status_class.map(toStatusClass).filter(Boolean);
  }
}

When it happens

Trigger: Passing filters: { status_class: ['200'] }, { status_class: ['3xx'] }, { status_class: ['success'] }, or mixing valid and invalid entries like ['2xx', '1xx'].

Common situations: Using raw HTTP status codes or full class names instead of the class notation; including 1xx/3xx which are not supported; building status_class from user-facing dropdowns with different labels.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• filter must be a boolean
• filter must be a finite number
• filter must be a non-empty array of non-empty strings
• filter monitor must be an object
• filter monitor.verdict must be pass, fail, or error

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

Appendix: source

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

    "auth_mode",
    "runtime_mode",
    "cache_status",
    "session_id",
    "client_user_hash",
    "trace_id",
    "member_user_id",
    "api_key_id",
    "optimization_id",
    "status_class",
  ];
  for (const key of stringListKeys) {
    const value = filters[key];
    if (value === undefined) continue;
    if (!Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== "string" || entry.trim() === "")) {
      throw new Error(`filter ${key} must be a non-empty array of non-empty strings`);
    }
    if (key === "status_class" && value.some((entry) => !["2xx", "4xx", "5xx"].includes(entry as string))) {
      throw new Error("filter status_class values must be 2xx, 4xx, or 5xx");
    }
  }
  for (const key of ["min_cost_usd", "max_cost_usd", "min_total_tokens", "max_total_tokens", "min_latency_ms", "max_latency_ms"]) {
    const value = filters[key];
    if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value))) {
      throw new Error(`filter ${key} must be a finite number`);
    }
  }
  for (const key of ["has_error", "compressed"]) {
    const value = filters[key];
    if (value !== undefined && typeof value !== "boolean") throw new Error(`filter ${key} must be a boolean`);
  }
  const monitor = filters.monitor;
  if (monitor !== undefined) {
    if (!monitor || typeof monitor !== "object" || Array.isArray(monitor)) throw new Error("filter monitor must be an object");
    const monitorUnknown = Object.keys(monitor).filter((key) => key !== "id" && key !== "verdict");
    if (monitorUnknown.length > 0) throw new Error(`filter monitor has unknown key(s): ${monitorUnknown.sort().join(", ")}`);
    if (typeof monitor.id !== "string" || monitor.id.trim() === "") throw new Error("filter monitor.id is required");

View on GitHub (pinned to 3ee70a1026)