{"record":{"id":"a11d17e8d22f435a","repo":"JuliusBrussee/caveman","slug":"installed-proxy-does-not-support-filtered-stats-or-html","errorCode":null,"errorMessage":"installed proxy does not support filtered stats or HTML reports; run caveman setup --install","messagePattern":"installed proxy does not support filtered stats or HTML reports; run caveman setup --install","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":15475,"sourceCode":"  let options;\n  try {\n    options = parseStatsOptions(argv);\n  } catch (error) {\n    console.error((error as Error).message);\n    commandUsage(STATS_USAGE);\n  }\n  const bin = cavemanBin(\"caveman-proxy\", \"CAVEMAN_PROXY_BIN\");\n  try {\n    const args = [\"stats\", \"--report\", ...options.filters];\n    if (!options.json || options.out) args.push(\"--write-report\");\n    if (options.out) args.push(\"--out\", resolve(options.out));\n    const out = execFileSync(bin, args, { encoding: \"utf8\", timeout: 60_000, maxBuffer: 32 * 1024 * 1024 });\n    const report = JSON.parse(out) as StatsCLIReport;\n    // Older companion binaries ignore --report. Keep their measurements\n    // readable, but never pretend they generated the new accounting report.\n    if (report.schema !== \"caveman.stats.v1\") {\n      if (options.filters.length || options.out || options.open) {\n        throw new Error(\"installed proxy does not support filtered stats or HTML reports; run caveman setup --install\");\n      }\n      process.stdout.write(out);\n      if (!options.json) process.stderr.write(\"Detailed stats require an updated proxy: caveman setup --install\\n\");\n      return;\n    }\n    if (options.json) process.stdout.write(out);\n    else {\n      process.stdout.write(renderStatsSummary(report));\n      if (report.report_path && (options.open || (!options.plain && learnTuiTerminal()))) openLearnReport(report.report_path);\n    }\n  } catch (error) {\n    console.error(`failed to read stats via ${bin}: ${(error as Error).message}`);\n    process.exit(1);\n  }\n}\n\ntype RecentProxyRow = {\n  ts: string;","sourceCodeStart":15457,"sourceCodeEnd":15493,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L15457-L15493","documentation":"The CLI runs the installed `caveman` companion binary with `--report` and expects a JSON payload with schema `caveman.stats.v1`. Older proxy binaries silently ignore the `--report` flag, so they cannot produce filtered stats or the HTML report. To avoid pretending an old binary did the accounting, the CLI throws this error instead of honoring `--filters`, `--out`, or `--open` against stale output.","triggerScenarios":"Running `caveman stats` with any of --filters, --out, or --open while the installed proxy binary is outdated (its JSON report lacks schema \"caveman.stats.v1\").","commonSituations":"User upgraded the npm CLI package but never re-ran `caveman setup --install`, so the companion binary on disk predates the stats v1 report feature; often after pulling a repo or switching branches that bumped the report schema.","solutions":["Run `caveman setup --install` to reinstall the up-to-date companion proxy binary.","Verify the installed binary version matches the CLI (`caveman stats` without filters should emit schema caveman.stats.v1).","If reinstall fails, run stats without --filters/--out/--open to view legacy plain output while updating."],"exampleFix":"// before (shell)\ncaveman stats --model claude-3 --out report.html\n// error: installed proxy does not support filtered stats...\n// after (shell)\ncaveman setup --install\ncaveman stats --model claude-3 --out report.html","handlingStrategy":"fallback","validationCode":"// shell\ninstalled_schema=$(caveman stats --json 2>/dev/null | jq -r '.schema // empty')\nif [ \"$installed_schema\" != \"caveman.stats.v1\" ]; then\n  echo \"proxy outdated; run: caveman setup --install\"\nfi","typeGuard":null,"tryCatchPattern":"// js\ntry {\n  await runStats({ filters, out, open });\n} catch (e) {\n  if (String(e.message).includes(\"does not support filtered stats\")) {\n    execFileSync(\"caveman\", [\"setup\", \"--install\"], { stdio: \"inherit\" });\n    return runStats({ filters, out, open });\n  }\n  throw e;\n}","preventionTips":["Re-run `caveman setup --install` whenever the CLI package updates.","Check the report schema field before using filtered stats in scripts.","Pin CLI and companion binary versions together in CI."],"tags":["cli","versioning","stats","incompatible-version"],"backgroundTag":"unsupported-operation","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}