JuliusBrussee/caveman · error

installed proxy does not support filtered stats or HTML…

Error message

installed proxy does not support filtered stats or HTML reports; run caveman setup --install

What it means

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.

Solutions

1. Run `caveman setup --install` to reinstall the up-to-date companion proxy binary.
2. Verify the installed binary version matches the CLI (`caveman stats` without filters should emit schema caveman.stats.v1).
3. If reinstall fails, run stats without --filters/--out/--open to view legacy plain output while updating.

Example fix

// before (shell)
caveman stats --model claude-3 --out report.html
// error: installed proxy does not support filtered stats...
// after (shell)
caveman setup --install
caveman stats --model claude-3 --out report.html

// shell
installed_schema=$(caveman stats --json 2>/dev/null | jq -r '.schema // empty')
if [ "$installed_schema" != "caveman.stats.v1" ]; then
  echo "proxy outdated; run: caveman setup --install"
fi

// js
try {
  await runStats({ filters, out, open });
} catch (e) {
  if (String(e.message).includes("does not support filtered stats")) {
    execFileSync("caveman", ["setup", "--install"], { stdio: "inherit" });
    return runStats({ filters, out, open });
  }
  throw e;
}

When it happens

Trigger: 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").

Common situations: 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.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• --days must be an integer from 0 to 3660
• duplicate
• recent stats was not a JSON array
• requires a value
• stats days must be between 0 and 3660

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

Appendix: source

Thrown at packages/cli/src/index.ts:15475

  let options;
  try {
    options = parseStatsOptions(argv);
  } catch (error) {
    console.error((error as Error).message);
    commandUsage(STATS_USAGE);
  }
  const bin = cavemanBin("caveman-proxy", "CAVEMAN_PROXY_BIN");
  try {
    const args = ["stats", "--report", ...options.filters];
    if (!options.json || options.out) args.push("--write-report");
    if (options.out) args.push("--out", resolve(options.out));
    const out = execFileSync(bin, args, { encoding: "utf8", timeout: 60_000, maxBuffer: 32 * 1024 * 1024 });
    const report = JSON.parse(out) as StatsCLIReport;
    // Older companion binaries ignore --report. Keep their measurements
    // readable, but never pretend they generated the new accounting report.
    if (report.schema !== "caveman.stats.v1") {
      if (options.filters.length || options.out || options.open) {
        throw new Error("installed proxy does not support filtered stats or HTML reports; run caveman setup --install");
      }
      process.stdout.write(out);
      if (!options.json) process.stderr.write("Detailed stats require an updated proxy: caveman setup --install\n");
      return;
    }
    if (options.json) process.stdout.write(out);
    else {
      process.stdout.write(renderStatsSummary(report));
      if (report.report_path && (options.open || (!options.plain && learnTuiTerminal()))) openLearnReport(report.report_path);
    }
  } catch (error) {
    console.error(`failed to read stats via ${bin}: ${(error as Error).message}`);
    process.exit(1);
  }
}

type RecentProxyRow = {
  ts: string;

View on GitHub (pinned to 3ee70a1026)