JuliusBrussee/caveman · warning

unknown trace filter(s): ${unknown.sort().join(", ")}

Error message

unknown trace filter(s): ${unknown.sort().join(", ")}

What it means

validateTraceFilters() allowlists filter keys against TRACE_FILTER_KEYS. Any key outside that set (workflow, agent, model, provider, error_code, auth_mode, runtime_mode, cache_status, session_id, client_user_hash, trace_id, member_user_id, api_key_id, optimization_id, status_class, the numeric/boolean ranges, and monitor) is rejected by name, sorted, in the error message.

Source

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

    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
    structuredContent,
    isError: true,
  };
}

async function withProjectQuery(client: AgentMcpClient, path: string): Promise<string> {
  if (!PROJECT_QUERY_PATHS.has(path)) return path;
  const projectId = await client.projectId();
  const query = new URLSearchParams({ project_id: projectId });
  return `${path}?${query}`;
}

function validateTraceFilters(args: JSONObject): void {
  const filters = args.filters;
  if (filters === undefined) return;
  if (!filters || typeof filters !== "object" || Array.isArray(filters)) throw new Error("filters must be an object");
  const unknown = Object.keys(filters).filter((key) => !TRACE_FILTER_KEYS.has(key));
  if (unknown.length > 0) throw new Error(`unknown trace filter(s): ${unknown.sort().join(", ")}`);
  const stringListKeys = [
    "workflow",
    "agent",
    "model",
    "provider",
    "error_code",
    "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) {

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Read the rejected key names in the message and map each to the closest allowlisted key (e.g. status -> status_class or error_code).
2. Check TRACE_FILTER_KEYS/this CLI version's tool schema for the exact accepted names.
3. Upgrade the caveman CLI if a filter you expect is missing — new filters arrive with CLI releases.

Example fix

// before
{ filters: { status: ["error"], model_name: ["gpt-4"] } }

// after
{ filters: { error_code: ["provider_error"], model: ["gpt-4"] } }

const TRACE_FILTER_KEYS = new Set(["workflow","agent","model","provider","error_code","auth_mode","runtime_mode","cache_status","session_id","client_user_hash","trace_id","member_user_id","api_key_id","optimization_id","status_class","min_cost_usd","max_cost_usd","min_total_tokens","max_total_tokens","min_latency_ms","max_latency_ms","has_error","compressed","monitor"]);
const bad = Object.keys(filters).filter((k) => !TRACE_FILTER_KEYS.has(k));
if (bad.length) throw new Error(`unknown filter keys: ${bad.join(", ")}`);

function isKnownFilterKey(k: string): boolean { return TRACE_FILTER_KEYS.has(k); }

When it happens

Trigger: Sending {"filters": {"model_name": [...]}} or {"status": "error"} — keys that are not in the recognized set; using dashboard/API filter names that differ from the MCP tool's vocabulary.

Common situations: Porting filter names from the REST API or UI that don't match this tool's schema; typos ("erro_code"); stale names after a CLI version renamed filters.

Related errors

• filters must be an object
• filter ${key} must be a non-empty array of non-empty strings
• filter status_class values must be 2xx, 4xx, or 5xx
• filter ${key} must be a finite number
• filter ${key} must be a boolean

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